Update documentation

[jhodgdon-drp]

Thanks for making this project available! I'm attempting to use it for a Drupal-related purpose... it's a bit tough to figure out, because it seems like the README files in various directories were not updated when the source was updated. The classes themselves do not document how to use them (like, for instance, it would be useful to have information about the configuration in each plugin class header)... so the README files are the only documentation pretty much. It would be helpful if they were updated.

Examples:

• The main project README implies the constructor for the main BackupMigrate class has arguments. It doesn't.
• So I'm not sure how to get the configuration to the plugins, or what use a Configuration object is... trying a few things out but I haven't got it working yet.
• The README at the top level doesn't match the README in the Main subdirectory.

Thanks!

[jhodgdon-drp]

Here is what I ended up with for working code for making a backup of a MySQL database, to a compressed file called database.mysql.gz (with a few variable inputs defined before this code):

    $config = new Config([
        'database1' => $db_info,
        'directory1' => [
          'directory' => $directory,
        ],
        'compressor' => [
          'compression' => 'gzip',
        ],
        'namer' => [
          'filename' => 'database',
          'timestamp' => FALSE,
        ],
        'excluder' => [
          'exclude_tables' => $exclude,
          'nodata_tables' => $no_data,
        ],
      ]);

    $manager = new BackupMigrate();
    $manager->services()->add('ArchiveReader', new TarArchiveReader());
    $manager->services()->add('ArchiveWriter', new TarArchiveWriter());
    $manager->services()->add('TempFileAdapter', new TempFileAdapter($this->getTempFilesDirectory()));
    $manager->services()->add('TempFileManager', new TempFileManager($manager->services()->get('TempFileAdapter')));

    $db_source = new MySQLiSource();
    $manager->services()->addClient($db_source);
    $manager->sources()->add('database1', $db_source);
    $manager->sources()->setConfig($config);

    $dir_dest = new DirectoryDestination();
    $manager->services()->addClient($dir_dest);
    $manager->destinations()->add('directory1', $dir_dest);
    $manager->destinations()->setConfig($config);

    $manager->plugins()->add('excluder', new DBExcludeFilter());
    $manager->plugins()->add('namer', new FileNamer());
    $manager->plugins()->add('compressor', new CompressionFilter());
    $manager->plugins()->setConfig($config);

    $manager->backup('database1', 'directory1');

The setup of $manager is identical for a restore, but the last line would be:

    $manager->restore('database1', 'directory1', 'database.mysql.gz');

I think this is about the minimal database backup example that actually works...

[jhodgdon-drp]

So... I'm just wondering if this kind of code is what this library intended for its API. It seems a bit complex:

• The Source and Destination plugin need access to several of the services. So you have to call services->addClient(), passing these in, to tell the Services collection about these source/destination plugins.
• The Source and Destination plugin need configuration.
• It seems like this could be simpler if the API was something like:

$manager = new BackupMigrate();
// Set up the config, which contains configuration for source, destination, and filters.
$manager->setConfig($config);
// Add all the services you need, with lines like these:
$manager->addService(.... );
// Add plugins. As each is added, an automatic call is made to configure it and add it as
// a client to the Services collection:
$manager->addSource(...);
$manager->addDestination(...);
$manager->addPlugin(...);

Just a thought... anyway the above code works. It just seems like you need to get too far into the guts of the services and plugin collections, and the BackupMigrate manager could have some helper methods that would take care of some of this stuff.

[jhodgdon-drp]

As one other note on documentation vs. the actual API... The main README.md file for this project states:

• A plugin manager maintains a list of injected plugins and configures them and injects services as needed.
• Services are managed and automatically injected by the service manager. A consuming application can add services by passing them to the service manager of the BackupMigrate object

So... it seems like the intention was that the BackupMigrate object would be the place to put services, and then the plugins would get them injected automatically. I am not seeing this happen in my use of these classes. It just doesn't seem like putting a service on BackupMigrate gets it into the plugins, without the calls to $services->addClient() that I noted in my first comment on this issue.

[aviggngyv]

Hi @jhodgdon-drp , I'm very want to thanks for your example code, it save my many time.

and I think this issue will help more people like me which looking for backup database solution.

so I want to place a patch to help other guys.

Encoding issues with non ASCIII texts
Related issue: [https://www.drupal.org/node/2749885]

the patch is :
https://www.drupal.org/files/issues/backup_migrate-ensure_utf8_name_setting-2749885-7.patch