Add support for filesystem adapters

[ejunker]

This is based on discussion in #24 where I want to be able to write the sitemaps and index to Amazon S3.

I think a very simple interface like this may work:

interface FilesystemAdapterInterface
{
    /**
     * Create a file or update if exists.
     *
     * @param string $path     The path to the file.
     * @param string $contents The file contents.
     *
     * @return bool True on success, false on failure.
     */
    public function put($path, $contents);
}

And then a FilesystemAdapter could be passed into the constructor and used when writing files.

[samdark]

No, it won't. If there are many URLs keeping it all in memory and then writing at once will cause huge memory usage.

[ejunker]

Ok, adding an append() method would be useful

interface FilesystemAdapterInterface
{
    /**
     * Create a file or update if exists.
     *
     * @param string $path     The path to the file.
     * @param string $contents The file contents.
     *
     * @return bool True on success, false on failure.
     */
    public function put($path, $contents);

    /**
     * Append content to an existing file.
     *
     * @param string $path     The path to the file.
     * @param string $content The content to append.
     *
     * @return bool True on success, false on failure.
     */
    public function append($path, $content);
}

[samdark]

How to handle overwriting of existing files?

[ejunker]

put() is essentially file_put_contents() without the FILE_APPEND flag set. If path does not exist, the file is created. Otherwise, the existing file is overwritten.

[samdark]

OK. Makes sense. @WinterSilence what do you think?

[WinterSilence]

@samdark Maybe - need tests.
@ejunker Few changes:
name: FilesystemAdapterInterface to StorageInterface,
methods: put, append to write(mixed $data),read() or get\set + add __construct(array $config = []).

Class implemented StorageInterface contain all logic to working with data.
StorageInterface::__construct(array $config = []):

$sitemap = new Sitemap(new Storage\File([$filePath = '...', $maxUrls = 1000, $bufferSize = 1000]));
$sitemap = new Sitemap(new Storage\MyCache([$key = '...', $ttl = 3600]));

[samdark]

How to get a list of file names written then?

[WinterSilence]

@samdark
1.Use method read()
2. Add method getFiles() for Storage\File (alias for read()?)
3. Auto create sitemapindex if Sitemap::fileCount > 1

[samdark]

That would do, yes.

[WinterSilence]

@samdark What's next?

[samdark]

If you have extra time to burn you may implement refactoring. Along with https://github.com/samdark/sitemap/tree/refactroring it could be released as a new major version.