Getting Started

Minimal Setup

Install the Bundle

composer require bongo/bongo-s3asset-installer-bundle

Enable in config/bundles.php:

return [
    // ...
    Bongo\S3AssetInstallerBundle\BongoS3AssetInstallerBundle::class => ['all' => true],
];

Configure AWS Credentials Add to .env (or parameters.yml):

AMAZON_S3_KEY=your-access-key
AMAZON_S3_SECRET=your-secret-key
AMAZON_S3_REGION=us-east-1
AMAZON_S3_BUCKET=your-bucket-name

Define Asset Base URLs In config/packages/framework.yaml (or config_prod.yml/config_dev.yml):

framework:
    assets:
        base_urls:
            - '%env(AWS_ASSET_BASE_URL)%'  # e.g., 'http://cdn.production.com/'

First Sync Run the console command to upload assets:
```
php bin/console bongo:s3:asset:install
```

First Use Case: Local Development Workflow

Symlink Assets Locally (Symfony default):
```
php bin/console assets:install public
```

Sync to S3 Before Deployment:

php bin/console bongo:s3:asset:install --env=prod

Verify URLs: Ensure {{ asset('bundles/...') }} resolves to S3-hosted paths (e.g., http://cdn.production.com/bundles/...).

Implementation Patterns

Workflow Integration

CI/CD Pipeline Add the sync command to your deployment script (e.g., after assets:install):

# Example in a deploy.sh script
php bin/console assets:install public
php bin/console bongo:s3:asset:install --env=prod

Environment-Specific Configs Use environment variables or separate configs for dev/prod:

# config/packages/bongo_s3_asset_installer.yaml
bongo_s3_asset_installer:
    amazon_s3_bucket: '%env(AWS_BUCKET_%kernel.environment%)%'

Define in .env.prod:

AWS_BUCKET_prod=production-assets
AWS_BUCKET_dev=dev-assets

Asset Versioning Leverage Symfony’s asset() function with versioning:
```
<link rel="stylesheet" href="{{ asset('css/app.css', 'prod') }}">
```
The bundle will upload the versioned file (e.g., app.abc123.css) to S3.

Advanced Patterns

Custom Asset Directories Override the default public/ path by extending the command:

// src/Command/CustomS3SyncCommand.php
use Bongo\S3AssetInstallerBundle\Command\S3AssetInstallerCommand;

class CustomS3SyncCommand extends S3AssetInstallerCommand {
    protected function getAssetDir() {
        return $this->getSymmetricFinder()->ignoreDotFiles()->in(__DIR__.'/../custom-assets');
    }
}

commands:
    App\Command\CustomS3SyncCommand: ~

Cache Control Add cache headers during upload by extending the S3Client service:

# config/services.yaml
Bongo\S3AssetInstallerBundle\Service\S3Uploader:
    arguments:
        $cacheControl: 'public, max-age=31536000'  # 1 year

Dry Run Mode Test sync without uploading by adding a --dry-run flag to the command (extend the base command).

Gotchas and Tips

Pitfalls

Permissions Issues
- Error: AccessDenied or NoSuchBucket.
- Fix: Verify IAM policies for the S3 bucket (e.g., s3:PutObject, s3:ListBucket).
- Debug: Run with --verbose to see raw AWS API responses:
```
php bin/console bongo:s3:asset:install --verbose
```

CORS Configuration

Error: Assets fail to load due to CORS.

Fix: Configure CORS on the S3 bucket to allow your domain:

<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <CORSRule>
        <AllowedOrigin>*</AllowedOrigin>
        <AllowedMethod>GET</AllowedMethod>
        <AllowedHeader>*</AllowedHeader>
    </CORSRule>
</CORSConfiguration>

Asset URL Mismatch
- Error: Local dev shows http://localhost/css/app.css, but prod shows http://cdn.production.com/css/app.css with broken links.
- Fix: Ensure base_urls in framework.assets matches the S3 bucket’s endpoint. Use absolute URLs in templates:
```
<img src="{{ asset('images/logo.png', 'prod') }}">
```
Symlink Conflicts
- Error: assets:install fails if public/bundles/ is a symlink pointing to S3-uploaded files.
- Fix: Run assets:install before bongo:s3:asset:install in your workflow.

Debugging Tips

Log AWS Requests Enable Guzzle logging in config/packages/bongo_s3_asset_installer.yaml:
```
bongo_s3_asset_installer:
    debug: true
```
Logs will appear in var/log/dev.log.

Check S3 Bucket

Verify files exist in the bucket via AWS Console or CLI:
```
aws s3 ls s3://your-bucket-name/bundles/
```

Ensure the bucket policy allows public reads (if needed):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::your-bucket-name/*"
    }
  ]
}

Command Options
- Skip Existing Files: Use --skip-existing to avoid re-uploading unchanged files.
- Limit Directories: Sync only specific folders with --dir=bundles,images.

Extension Points

Custom File Filtering Override the getFiles() method in the command to exclude files (e.g., .map files):

protected function getFiles() {
    return $this->getSymmetricFinder()
        ->ignoreDotFiles()
        ->exclude('*.map')
        ->in($this->getAssetDir());
}

Pre/Post-Sync Hooks Add events to the bundle’s S3AssetInstallerEvents (if supported) or use Symfony’s event dispatcher:

// src/EventListener/S3SyncListener.php
use Symfony\Component\HttpKernel\Event\PostResponseEvent;

class S3SyncListener {
    public function onKernelResponse(PostResponseEvent $event) {
        if ($event->getRequest()->getPathInfo() === '/sync-assets') {
            // Trigger sync logic
        }
    }
}

Parallel Uploads Optimize performance by enabling parallel uploads (if the bundle supports it) or use a queue system (e.g., Symfony Messenger) for large projects:
```
# config/packages/messenger.yaml
framework:
    messenger:
        transports:
            s3_uploads: '%env(MESSENGER_TRANSPORT_DSN)%'
```

Bongo S3Asset Installer Bundle Laravel Package