y.st./source/pages/en/weblog/2016/01-January/09.xhtml

<?php
/**
 * <https://y.st./>
 * Copyright © 2016 Alex Yst <mailto:copyright@y.st>
 * 
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <https://www.gnu.org./licenses/>.
**/

$xhtml = array(
	'title' => '<code>\\scandir()</code>',
	'body' => <<<END
<p>
	For some strange reason, my spider keeps quitting on me without an error message.
	At least now, quitting does not cause all the data to be lost.
</p>
<p>
	I found a function in the $a[PHP] manual that I had not seen before: <a href="https://secure.php.net/manual/en/function.scandir.php"><code>scandir()</code></a>.
	This function lists all files in a directory, and even does it alphabetically.
	As far as I can tell, the only thing that directory handles and <code>\\Directory</code> object are good for is listing directories, so this simple function obsoletes both, as both are a pain to use.
	Literally every time that I want to use them, I have to consult the manual again to be sure I am using them correctly because you cannot just iterate over them as expected.
	Instead, you must explicitly check each return value for being identical to (not just equal to) false while at the same time assigning the values to variables.
	I have always thought that such a directory-listing function should exist, but could never find it, so I always just built my own.
	This function also obsoletes my own custom <code>dir()</code> function, which just creates a dir object, iterates over it, then alphabetizes and returns the results, so I am removing it.
	It obsoletes my dir class as well, though I will be keeping that due to it being one of my wrapper classes.
</p>
<p>
	While working on wrapping stream resources, I found some interesting things.
	First, that <a href="https://secure.php.net/manual/en/class.streamwrapper.php">class prototype that I found yesterday</a> seems to be for use with the <a href="https://secure.php.net/manual/en/function.stream-wrapper-register.php"><code>stream_wrapper_register()</code> function</a>.
	It is completely irrelevant to my current project of wrapping up resources with their function.
	Second, and more interestingly, I do not see any functions for actually creating a <a href="https://secure.php.net/manual/en/ref.stream.php">stream resource</a>.
	Instead, as best I can tell, the stream functions are used on resources created by more specific functions.
	For example, I think that the stream functions apply to <a href="https://secure.php.net/manual/en/book.dir.php">directory resources</a> and <a href="https://secure.php.net/manual/en/book.ftp.php">$a[FTP]</a> resources.
	I was thinking about making my stream class into an abstract class for other classes such as the $a[FTP] class to extend, but there is a small issue with that plan.
	Specifically, my directory class already extends the default, half-implemented <code>\\Directory</code> class.
	I can instead make it into a trait, though that means reworking several classes.
	Specifically, my wrapper classes currently use self::\$resource to hold the resource handle, but <code>\\Directory</code> uses <code>self::\$handle</code> instead.
	In order to make the trait work, I will need to change any class that uses the stream trait to match.
	For consistency, I will probably change all the wrapper classes to match whether they use the stream trait or not.
	The one down side to using a trait instead of an abstract class is that I cannot use type hints to require that certain function take only resource wrappers as arguments.
	From the looks of it though, if this becomes a problem, I can create an interface to go with the trait.
	An interface cannot define working methods and a trait cannot be used for type hinting, but together, they can get the job done.
</p>
<p>
	I ran into some strange functions relating to &quot;bucket objects&quot; and &quot;brigade resources&quot;.
	There is no documentation that I can find on where brigade resources come from or how to create them.
	The only scrap of information that I can find is on the <a href="https://secure.php.net/manual/en/function.stream-bucket-prepend.php"><code>\\stream_bucket_prepend()</code> function</a>&apos;s documentation page.
	This documentation says that a brigade resource is a resource used to contain bucket objects, but that is all that is says bout them.
	As for bucket object, I ran some tests on my machine, and it seems that bucket objects are just <code>\\stdClass</code> objects that have three properties: a string, an integer, and a &quot;userfilter.bucket&quot; resource.
	I am also having trouble wrapping the stream_socket_*() functions, as their descriptions are not consistent.
	Some appear to work on a specific type of resource that is used for socket streams, but some imply that they are for streams in general.
</p>
<p>
	My <a href="/a/canary.txt">canary</a> still sings the tune of freedom and transparency.
</p>
END
);