Getting Started

Minimal Steps to Begin

Installation Add the bundle to your Symfony project via Composer:

composer require campusdomar/pumukit-import-bundle

Enable the bundle in config/bundles.php:

return [
    // ...
    CampusDomar\PumukitImportBundle\PumukitImportBundle::class => ['all' => true],
];

Configuration Follow the Installation Guide to configure config/packages/pumukit_import.yaml with your PuMuKIT database credentials and import settings.
First Use Case: Importing a Series Export a series from PuMuKIT v1.7 in XML format (using PuMuKIT1-data-export). Place the XML file in a dedicated directory (e.g., var/imports/). Run the import command:
```
php bin/console pumukit:import:series /path/to/your/file.xml
```

Implementation Patterns

Workflows

Batch Processing Use the bundle to import multiple XML files sequentially:
```
php bin/console pumukit:import:series file1.xml file2.xml
```
For large datasets, split XML files into smaller chunks to avoid memory issues.

Integration with Custom Logic Extend the bundle’s importer by creating a custom service that implements CampusDomar\PumukitImportBundle\Service\ImporterInterface:

namespace App\Service;

use CampusDomar\PumukitImportBundle\Service\ImporterInterface;
use CampusDomar\PumukitImportBundle\Entity\Series;

class CustomSeriesImporter implements ImporterInterface
{
    public function import(Series $series): void
    {
        // Custom logic (e.g., validate, transform, or enrich data)
    }
}

Scheduled Imports Use Symfony’s scheduler (e.g., with cron or a task runner like spatie/symfony-cron) to automate imports:

# config/packages/schedule.yaml
schedule:
    import_series:
        command: 'pumukit:import:series /path/to/file.xml'
        cron: '0 3 * * *' # Run daily at 3 AM

Integration Tips

Database Compatibility: Ensure your PuMuKIT database schema matches the expected structure (e.g., tables for series, episodes, and publication_channels). Refer to PuMuKIT’s schema docs.

Logging: Enable debug logging in config/packages/monolog.yaml to track import progress and errors:

handlers:
    pumukit_import:
        type: stream
        path: var/log/pumukit_import.log
        level: debug

Validation: Validate XML files against the PuMuKIT export schema before import to catch malformed data early. Use tools like xmllint or PHP’s DOMDocument::schemaValidate().

Gotchas and Tips

Pitfalls

XML Parsing Errors
- Issue: Malformed XML or unsupported elements in the export file will cause import failures.
- Fix: Validate XML files pre-import:
```
xmllint --schema path/to/pumukit_schema.xsd your_file.xml
```
  Or use PHP’s SimpleXMLElement to catch parsing errors:
```
$xml = simplexml_load_file($filePath);
if ($xml === false) {
    throw new \RuntimeException("Invalid XML file");
}
```

Duplicate Data

Issue: Importing the same series multiple times may create duplicates.

Fix: Use the unique_identifier field in the XML (if available) to skip existing records. Extend the importer to check for duplicates:

$existingSeries = $entityManager->getRepository(Series::class)
    ->findOneBy(['uniqueIdentifier' => $series->getUniqueIdentifier()]);
if ($existingSeries) {
    $this->logger->info('Skipping duplicate series', ['id' => $series->getUniqueIdentifier()]);
    return;
}

Missing Publication Channels
- Issue: The import may fail if referenced publication channels (e.g., publication_channel_id) don’t exist in the database.
- Fix: Pre-populate required channels or use the Allow Publication Channels Guide to dynamically create them during import.
Memory Limits
- Issue: Large XML files may exceed PHP’s memory limit (memory_limit).
- Fix: Increase the limit in php.ini or process files in chunks using SimpleXMLIterator:
```
$xml = simplexml_load_file($filePath);
foreach ($xml->series as $series) {
    // Process one series at a time
}
```

Debugging

Command-Line Flags: Use verbose output for debugging:

php bin/console pumukit:import:series file.xml --verbose

Doctrine Events: Listen to prePersist and preUpdate events to inspect entity changes:

# config/services.yaml
App\EventListener\SeriesImportListener:
    tags:
        - { name: doctrine.event_listener, event: prePersist }

// src/EventListener/SeriesImportListener.php
public function prePersist(LifecycleEventArgs $args): void
{
    $entity = $args->getObject();
    if ($entity instanceof Series) {
        $this->logger->debug('Importing series', ['data' => $entity->toArray()]);
    }
}

Extension Points

Custom Mappers Override the default XML-to-entity mapping by creating a custom mapper:

namespace App\Mapper;

use CampusDomar\PumukitImportBundle\Mapper\SeriesMapperInterface;
use CampusDomar\PumukitImportBundle\Entity\Series;

class CustomSeriesMapper implements SeriesMapperInterface
{
    public function map(array $xmlData): Series
    {
        $series = new Series();
        // Custom mapping logic
        return $series;
    }
}

Post-Import Actions Trigger actions after import (e.g., generate thumbnails, send notifications):

# config/packages/pumukit_import.yaml
pumukit_import:
    post_import_actions:
        - App\Service\ThumbnailGenerator
        - App\Service\NotificationSender

Custom Validation Add validation rules to the importer:

use Symfony\Component\Validator\Constraints as Assert;

$series->addConstraint(new Assert\Length([
    'min' => 3,
    'minMessage' => 'Title must be at least 3 characters long',
]));

Configuration Quirks

Database Transactions: The bundle may wrap imports in transactions. For large imports, disable transactions to avoid timeouts:
```
# config/packages/pumukit_import.yaml
pumukit_import:
     use_transactions: false
```

Environment Variables: Prefer environment variables for sensitive data (e.g., database credentials):

# .env
PUMUKIT_DB_USER=your_user
PUMUKIT_DB_PASSWORD=your_password

Then reference them in pumukit_import.yaml:

pumukit_import:
     db:
         user: '%env(PUMUKIT_DB_USER)%'
         password: '%env(PUMUKIT_DB_PASSWORD)%'

Pumukit Import Bundle Laravel Package