bedita/import-tools

Import Tools for data import with BEdita

v1.5.0 2024-09-05 10:27 UTC

Requires

• php: >= 7.4
• bedita/api: ^5.27
• bedita/core: ^5.27
• bedita/i18n: ^4.4
• cakephp/cakephp: ^4.5
• fakerphp/faker: ^1.23

Requires (Dev)

• cakephp/cakephp-codesniffer: ~4.7
• phpstan/extension-installer: ^1.0
• phpstan/phpstan: ^1.8
• phpstan/phpstan-deprecation-rules: ^1.0
• phpunit/phpunit: ^9.5

LGPL-3.0-or-later

• Atlas Consulting s.r.l.
• Chia Lab s.r.l.

README

Installation

First, if vendor directory has not been created, you have to install composer dependencies using:

composer install

You can install this plugin into your CakePHP application using composer.

The recommended way to install composer packages is:

composer require bedita/import-tools

Commands

AnonymizeUsersCommand

This command provides a tool to anonymize users. Usage examples

// anonymize all users (except user by ID 1, admin)
$ bin/cake anonymize_users

// anonymize users by id 2,3,4
$ bin/cake anonymize_users --id 2,3,4

// anonymize all users except users by id 1,2,3
$ bin/cake anonymize_users --preserve 1,2,3

ImportCommand

This command provides a tool to import data from csv file.

Usage examples:

# basic
$ bin/cake import --file documents.csv --type documents
$ bin/cake import -f documents.csv -t documents

# dry-run
$ bin/cake import --file articles.csv --type articles --dryrun yes
$ bin/cake import -f articles.csv -t articles -d yes

# destination folder
$ bin/cake import --file news.csv --type news --parent my-folder-uname
$ bin/cake import -f news.csv -t news -p my-folder-uname

# translations
$ bin/cake import --file translations.csv --type translations
$ bin/cake import -f translations.csv -t translations

ImportProjectCommand

You could use this command when you are copying a remote database to a locale database, and after that you want to "adjust" applications and users. Applications and users in default datasource will be updated.

Before launching it, you should setup properly default and import datasources in config/app_local.php. Example:

'Datasources' => [
    // the target database
    'default' => [
        'className' => 'Cake\Database\Connection',
        'driver' => 'Cake\Database\Driver\Mysql',
        'host' => '***********',
        'port' => '***********',
        'username' => '***********',
        'password' => '***********',
        'database' => '***********',
        // ...
    ],
    // the remote database you want to you as source
    'import' => [
        'className' => 'Cake\Database\Connection',
        'driver' => 'Cake\Database\Driver\Mysql',
        'host' => '***********',
        'port' => '***********',
        'username' => '***********',
        'password' => '***********',
        'database' => '***********',
        // ...
    ],
],

Usage example:

$ bin/cake import_project

TranslateFileCommand

This command provides a tool to translate the content of a file from one language to another, using a translator service (i.e., set in config/app_local.php).

Translator service configuration example:

'Translators' => [
    'deepl' => [
        'name' => 'DeepL',
        'class' => '\BEdita\I18n\Deepl\Core\Translator',
        'options' => [
            'auth_key' => '************',
        ],
    ],
]

Usage example:

$ bin/cake translate_file \
  --input articles-en.txt \
  --output articles-it.txt \
  --from en \
  --to it \
  --translator deepl

TranslateObjectsCommand

This command provides a tool to translate the content of objects from one language to another, using a translator service (i.e., set in config/app_local.php, as described above).

Usage examples:

# basic
$ bin/cake translate_objects \
  --from en \
  --to it \
  --engine deepl

# dry-run
$ bin/cake translate_objects \
  --from en \
  --to it \
  --engine deepl \
  --dry-run yes

# limit
$ bin/cake translate_objects \
  --from en \
  --to it \
  --engine deepl \
  --limit 10

# status
$ bin/cake translate_objects \
  --from en \
  --to it \
  --engine deepl \
  --status draft

# type
$ bin/cake translate_objects \
  --from en \
  --to it \
  --engine deepl \
  --type articles

Utilities

You can find some utility classes in src/Utility folder.

CsvTrait

This trait provides readCsv method to progressively read a csv file line by line.

Usage example:

use BEdita\ImportTools\Utility\CsvTrait;

class MyImporter
{
    use CsvTrait;

    public function import(string $filename): void
    {
        foreach ($this->readCsv($filename) as $obj) {
            // process $obj
        }
    }
}

FileTrait

This trait provides readFileStream method to open "read-only" file stream (you can use local filesystem or adapter).

Usage example:

use BEdita\ImportTools\Utility\FileTrait;

class MyImporter
{
    use FileTrait;

    public function read(string $file): void
    {
        [$fh, $close] = $this->readFileStream($path);

        try {
            flock($fh, LOCK_SH);
            // do your stuff
        } finally {
            $close();
        }
    }
}

TreeTrait

This trait provides setParent method to save the parent for a specified entity.

Usage example:

use BEdita\ImportTools\Utility\TreeTrait;

class MyImporter
{
    use TreeTrait;

    public function import(string $filename, string $destination): void
    {
        foreach ($this->readCsv($filename) as $obj) {
            $this->setParent($obj, $destination);
        }
    }
}

Import

This class provides functions to import data from csv files into BEdita.

Public methods are:

• saveObjects: read data from csv and save objects
• saveObject: save a single object
• saveTranslations: read data from csv and save translations
• saveTranslation: save a single translation
• translatedFields: get translated fields for a given object

Usage example:

use BEdita\ImportTools\Utility\Import;

class MyImporter
{
    public function import(string $filename, string $type, ?string $parent, ?bool $dryrun): void
    {
        $import = new Import($filename, $type, $parent, $dryrun);
        $import->saveObjects();
    }
}