Core Dam Bundle Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**
   Add the bundle to your Laravel project via Composer:
   ```bash
   composer require anzusystems/core-dam-bundle

Register the bundle in config/app.php under extra.bundles.

2. Environment Configuration Configure required environment variables (e.g., DB_CORE_DAM_BUNDLE_* for database connections, GOOGLE_PUBSUB_SA_KEY for PubSub). Example:

   DB_CORE_DAM_BUNDLE_DATABASE_URL=mysql://user:pass@localhost/db_name
   GOOGLE_PUBSUB_SA_KEY=your-service-account-key
   

3. First Use Case: Uploading an Asset Use the AssetFacade to upload and process an asset:

   use AnzuSystems\CoreDamBundle\Facades\AssetFacade;
   
   $asset = AssetFacade::createFromStorage(
       'path/to/file.jpg',
       'image/jpeg',
       ['authors' => ['author1@example.com']]
   );
   

4. Key Facades

   • AssetFacade: Core asset operations (create, update, search).
   • AssetFileFacade: File-specific operations (e.g., generating public routes).
   • DistributionFacade: Manage asset distributions (e.g., JWPlayer, YouTube).

5. Documentation Start with the changelog for feature highlights and the src/ directory for API references. Focus on:

   • Facade/ for high-level operations.
   • Entity/ for data models (e.g., Asset, AssetFile, Distribution).
   • Event/ for custom event listeners.

Implementation Patterns

1. Asset Workflows

Upload and Process Assets

Use AssetFacade::createFromStorage() for direct uploads or AssetFacade::createFromUrl() for remote assets (e.g., YouTube thumbnails). Example:

$asset = AssetFacade::createFromStorage(
    $filePath,
    $mimeType,
    [
        'authors' => ['author@example.com'],
        'keywords' => ['keyword1', 'keyword2'],
        'customData' => ['field' => 'value'],
    ]
);

• Metadata Extraction: The bundle auto-extracts EXIF/IPTC metadata (e.g., authors, keywords) during upload. Override with authors, keywords, or customData.
• Async Processing: Use AssetFacade::process() to trigger background jobs (e.g., image resizing, metadata indexing).

Bulk Operations

Leverage bulk APIs for efficiency:

// Bulk metadata update
AssetFacade::bulkUpdateMetadata(
    [$assetId1, $assetId2],
    ['customData' => ['new_field' => 'new_value']]
);

// Bulk job processing (e.g., image copies)
$job = new JobImageCopy($assetIds, $targetExtSystem);
AssetFacade::dispatchJob($job);

2. Distributions

Generate Distributions

Create distributions for external systems (e.g., JWPlayer, YouTube):

use AnzuSystems\CoreDamBundle\Entity\Distribution\JwDistribution;

$distribution = new JwDistribution();
$distribution->setAsset($asset);
$distribution->setFileId($asset->getMainFile()->getId());
$distribution->setDirectSourceUrl($asset->getPublicUrl());

DistributionFacade::save($distribution);

• Public URLs: Use AssetFileFacade::generatePublicRoute() to generate signed URLs or direct links:

  $publicUrl = AssetFileFacade::generatePublicRoute(
      $assetFile->getId(),
      $extSystemId,
      $expiresAt = null // Optional expiry time
  );
  

3. Search and Filtering

Elasticsearch Queries

Use the AssetQueryFactory to build searches:

use AnzuSystems\CoreDamBundle\Query\AssetQueryFactory;

$query = AssetQueryFactory::create()
    ->addFilter('authors', 'author@example.com')
    ->addFilter('customDataKey', 'field')
    ->addFilter('customDataValue', 'value')
    ->setPage(1, 20);

$results = AssetFacade::search($query);

• Priority Boosters: Add boost to text searches for relevance tuning:

  ->addTextSearch('keyword1', 2.0) // Higher boost = higher priority
  

Faceted Search

Leverage Elasticsearch aggregations for faceted navigation:

$query = AssetQueryFactory::create()
    ->addAggregation('authors', 'terms', 10)
    ->addAggregation('licences', 'terms', 5);

$results = AssetFacade::search($query);

4. Event-Driven Extensions

Listen to Asset Events

Extend functionality via events (e.g., AssetFileCopiedEvent):

use AnzuSystems\CoreDamBundle\Event\AssetFileCopiedEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class MyAssetSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [
            AssetFileCopiedEvent::class => 'onAssetFileCopied',
        ];
    }

    public function onAssetFileCopied(AssetFileCopiedEvent $event)
    {
        // Custom logic (e.g., send notification, update analytics)
    }
}

Register the subscriber in services.yaml:

services:
    App\EventSubscriber\MyAssetSubscriber:
        tags:
            - { name: kernel.event_subscriber }

5. Image Processing

Generate Image Variants

Use AssetFileFacade to generate resized/cropped images:

$resizedFile = AssetFileFacade::generateOptimalResize(
    $assetFile->getId(),
    800, // width
    600, // height
    'png' // format
);

• Crop Cache: Disable via config (anzusystems_core_dam.crop_cache.enabled: false) if needed.
• Public/Private Images: Toggle with flags.publicExportEnabled on AssetFile.

6. Podcast and Video Management

Podcast RSS Feeds

Manage podcast episodes and RSS URLs:

use AnzuSystems\CoreDamBundle\Entity\PodcastEpisode;

$episode = new PodcastEpisode();
$episode->setPodcast($podcast);
$episode->setTitle('Episode 1');
$episode->setRssUrl('https://example.com/rss.xml');
$episode->setMobileOrderPosition(1);

PodcastFacade::save($episode);

• RSS Validation: The bundle validates RSS URL length and structure.

Video Distributions

For video assets, use VideoShowFacade and VideoShowEpisodeFacade:

$videoShow = VideoShowFacade::create(
    'My Show',
    ['authors' => ['author@example.com']]
);

$episode = VideoShowEpisodeFacade::create(
    $videoShow,
    'Episode 1',
    $assetId
);

7. Licensing and Access Control

Assign Licences

Attach licences to assets:

$asset->addLicence($licence);
AssetFacade::save($asset);

• Bulk Licence Updates: Use AssetFacade::bulkUpdateLicences() for large-scale updates.

Voter-Based Access Control

Extend access control with custom voters:

use AnzuSystems\CoreDamBundle\Security\Voter\AssetLicenceAwareVoter;

class MyAssetVoter extends AssetLicenceAwareVoter
{
    protected function supports(string $attribute, $subject): bool
    {
        return $attribute === 'EDIT' && $subject instanceof Asset;
    }

    protected function voteOnAttribute(string $attribute, $subject, TokenInterface $token): bool
    {
        // Custom logic
        return true;
    }
}

8. Background Jobs

Queue Jobs for Async Processing

Dispatch jobs for non-blocking operations:

use AnzuSystems\CoreDamBundle\Job\JobImageOptimalResizeReprocess;

$job = new JobImageOptimalResizeReprocess($assetFileId);
AssetFacade::dispatchJob($job);

• Job Processing: Jobs are processed by JobImageCopyProcessor, JobAuthorCurrentOptimizeProcessor, etc. Check src/Job/ for available jobs.

9. Custom Data and Metadata

Manage Custom Metadata

Store and query custom metadata:

// Set custom data
$asset->setCustomData(['field' => 'value']);

// Search by custom data
$query = AssetQueryFactory::create()
    ->addFilter('customDataKey', 'field')
    ->addFilter('customDataValue', 'value');

Metadata Validation

Validate custom metadata during upload:

use AnzuSystems\CoreDamBundle\Validator\Constraints\CustomMetadata;

class MyAssetType extends AbstractAssetType
{
    public function getValidationConstraints(): array
    {
        return [
            new CustomMetadata([
                'field' => 'required|string',
                'tags' => 'array',
            ]),
        ];
    }
}

10.