[v7.3+]MediaCenter

Intro

This document provides an overview and detailed explanation of the update of "MediaCenter".

The MediaCenter is a feature designed to allow users to upload multimedia files directly to Xalok without having to access the article section.

The tool's interface and file uploading process have been updated, making it easier for users to manage the process.

Using

Upgrading an existing project

MediaCenter is available since v7.3+. If your project started from the skeleton after 05.02.2025, there's nothing you need to do. To upgrade an existing project:

git remote add skeleton git@git.xalok.com:HML/skeleton-2021.git
git fetch skeleton
git cherry-pick cfc9601bc2337f14fb1abc39b335a3d6f92a6838
git cherry-pick cfbf80317b4742e971ba76780c311afa1faa0b0e
composer update wfcms/standard
make install-assets
make install-sf-assets

Changes in security.access_control

For security reasons, it is necessary to protect the Mediacenter endpoints to prevent them from being publicly accessible.

• If the project does not use security_access_control.yml from wfcms/standard, add the following line to the project's security.access_control configuration directive (usually in app/admin/config/security.yml)):

- {
      path: '^/((%regex_locales%)/)?mediacenter',
      role: [ROLE_CONTENT_PAGE_ADD, ROLE_CONTENT_PAGE_EDIT],
  }

Deployment

Role Configuration for AWS Environments

In AWS environments, a role with limited permissions must be configured so that Mediacenter can only perform actions on the specific bucket and directory it operates in.

Role Permissions

The user associated with this role must have permissions to:

• Write in the S3 bucket directory uploads/tmp/.

Project Configuration

To ensure the service can use these credentials correctly, the following values must be configured in the project environment:

aws_mediacenter_access: MEDIACENTER_USER_ACCESS
aws_mediacenter_secret: MEDIACENTER_USER_SECRET
aws_mediacenter_arn: MEDIACENTER_USER_ARN  # Example: 'arn:aws:iam::123456787:role/S3AccessBucketData-projectMediaCenter'

CORS headers

This configuration should be done by HS

Ensure S3 has the correct permissions:

• Open Amazon S3 in the AWS console.
• Select the bucket where you upload the files.
• Go to the Permissions tab → Cross-origin resource sharing (CORS).
• Add ETag to ExposedHeaders
• If you already have a CORS configuration, add ETag to it. If you don't have one, use this minimal configuration:

[
    {
        "AllowedHeaders": ["*"],
        "AllowedMethods": ["GET", "PUT", "POST", "HEAD"],
        "AllowedOrigins": ["https://admin-skeleton.xalok.com"],
        "ExposeHeaders": ["ETag"],
        "MaxAgeSeconds": 3000
    }
]

Note: Please note that you need to replace the AllowedOrigins value with the URI of the project's admin.

Cleanup

To avoid accumulating unnecessary temporary files (files that have been uploaded but have not been imported/linked to any database objects), it is important to set up and execute the following command regularly:

app/admin/console wf:cms:mediacenter:remove-temp-files

Failure to do so may result in excessive storage usage.

Developing

Overview of the update

The changes in this version of MediaCenter include:

• Visual update of the tool: The layout and Vue components have been modernized.
• Search functionality added: A search bar has been integrated into the MediaCenter view.
• File-specific forms: Forms for each file type have been added, allowing users to edit the information of uploaded elements individually or in bulk.
• Upload process modifications:
  • For development environments, a local upload system has been implemented.
  • For environments using AWS S3, multipart uploads have been enabled using the AWS SDK v2.
  • The system now supports the addition of new providers or upload systems.
• Integration into the wfcms/standard repository: The MediaCenter component is now part of the wfcms/standard repository, eliminating the need for independent installation.

@WfCmsMediaCenterBundle - Integration with wfcms/standard

In wfcms/standard v7.3+, the MediaCenter code can be found in the following directory: Wf/Bundle/MediacenterBundle (vendor/wfcms/standard/Wf/Bundle/MediacenterBundle).

The MediaCenter is integrated as an independent bundle under the name @WfCmsMediaCenterBundle:

\Wf\Bundle\MediacenterBundle\WfCmsMediaCenterBundle

This integration allows developers to use the MediaCenter functionality seamlessly within a wfcms/standard project without requiring additional installation steps.

Main Directories

This is the main directory structure within the project, along with a brief description of its purpose.

• Command: Contains internal commands used in Mediacenter.
• Controller: Holds the controllers that serve as the entry point to the application.
• Resources: Contains resource files, including the folder for views and JavaScript logic.
  • Javascripts/media: Contains Vue.js components and the JavaScript logic related to media management.
• Services: Includes files implementing business logic by Symfony.
• Utils: A collection of common utility files used in Symfony. It contains reusable functions and classes that facilitate various operations within the Mediacenter.

Setup and Configuration

This section explains how to set up the local development environment for MediaCenter. Only MediaCenter-specific configurations will be detailed, meaning that other Xalok configuration processes will be omitted at this stage.

Depending on the specific needs or scenarios, you may need to modify the functionality of MediaCenter. Below are the possible scenarios and their corresponding setup requirements:

Working on the interface

If you are making UI-related modifications (e.g., Vue component updates, layout changes), no additional configuration is required beyond the standard development setup.

Vue Views and Main Components

Below is a breakdown of the key Vue components used in Mediacenter, detailing their purpose and interactions.

• Wf/Bundle/MediacenterBundle/Resources/public/javascripts/media/Upload.vue: Serves as the main container for all Mediacenter elements.
• Wf/Bundle/MediacenterBundle/Resources/public/javascripts/media/Tabs.vue: Provides tab-based navigation for selecting between file uploads and searching by type.
• Wf/Bundle/MediacenterBundle/Resources/public/javascripts/media/components/WfmcUpload.vue: A dedicated container for handling file uploads.
• Wf/Bundle/MediacenterBundle/Resources/public/javascripts/media/components/FileEditModal.vue: Manages the file editing modal and triggers file uploads, modifications, or deletions.
  • Wf/Bundle/MediacenterBundle/Resources/public/javascripts/media/components/ModalContainer.vue: Handles the assignment of metadata to uploaded files (e.g., names, entity-specific values).
  • Wf/Bundle/MediacenterBundle/Resources/public/javascripts/media/components/FileCarousel.vue: Contains the selector and preview display for uploaded content.
    • Wf/Bundle/MediacenterBundle/Resources/public/javascripts/media/components/preview/GenericPreview.vue: Responsible for rendering individual file previews. It dynamically loads the appropriate preview component based on the file type:
      • AudioPreview.vue (audio files)
      • FilePreview.vue (generic file types)
      • ImagePreview.vue (image files)
      • VideoPreview.vue (video files)

Working on the S3 integration

Changes Related to Cloud Uploads

• Since local environments do not have direct access to cloud services (e.g., AWS S3, GCP, etc.), you will need to configure an emulation of the cloud environment you intend to work with.
• In MediaCenter v2.0, only S3 uploads have been implemented. Therefore, this documentation will focus on configuring an S3 emulation environment.
• Local Changes Without Cloud Environment Emulation
  • No need for modifying docker-compose.
  • Local file uploads use Symfony’s configured filesystem.

Docker configuration

In the docker/docker-compose.yml file, the s3 service has been added. This service includes a container created from the s3-ninja image, which is responsible for emulating uploads to AWS S3. If this service is commented out, uncomment the relevant lines and ensure that the s3 container is running.

For the necessary configuration changes to simulate S3 uploads and further details, refer to:

AWS S3 - Development with S3 Ninja

Configuration to Simulate AWS STS Requests

To avoid exposing AWS credentials in deployed environments (such as pre-production or production environments), a request to the AWS STS (Security Token Service) has been implemented. This service generates temporary credentials, which are then used for uploading files to S3.

Since S3-Ninja does not support this type of request, if you need to develop features related to AWS STS, you must use the LocalStack Docker image instead.

For detailed documentation on AWS STS requests, refer to: AWS STS - Development with LocalStack.

Mediacenter: Technical Details

File Upload Process

In the current version of MediaCenter, in cloud environments, the upload process is designed to use multipart upload, optimizing file transfers, especially for multiple large files. This approach splits files into smaller parts and uploads them in parallel, improving speed and reducing the risk of transfer failures.

In local development environments, uploads are performed using a standard process, as connectivity issues or interruptions that would justify the use of multipart upload are not expected.

The file upload process follows these steps:

1. Adding Files

   Users add files through the Mediacenter upload tab.

2. Temporary Upload

   • When files are added, they are initially uploaded to a temporary location.
   • This background upload occurs while the user edits file details, significantly reducing the waiting time when finalizing the process.

3. Editing and Validation

   • Users assign required metadata to each uploaded file.
   • The system prevents confirmation until all mandatory fields are completed.

   At this stage, multiple files can be edited at once. If several files share a common field and that field is modified, all selected files will receive the same value where applicable. For example, if multiple images are selected and a common "alt" value is added, it will be applied to all selected files.

4. Finalizing the Upload

   • Once the changes are confirmed, files are moved from the temporary location to their final destination.
   • Symfony recognizes this final path as the valid storage location for system integration.
   • The corresponding entity is then saved to persist the file information.

Upload process: Technical Details

File upload and deletion operations are triggered by FileEditModal.vue, which injects the UploaderService (Wf/Bundle/MediacenterBundle/Resources/public/javascripts/media/uploaderService.js).

This service is responsible not only for handling file uploads and deletions but also for:

• Validating files
• Managing browser cache
• Persisting uploaded elements

Storage Management

To interact with the storage system, UploaderService relies on storage_service (Wf/Bundle/MediacenterBundle/Resources/public/javascripts/media/storage_service.js).

This service determines whether files are uploaded to local storage or a cloud provider based on the configuration set in cnf.uploadsStorageLocal (defined in Wf/Bundle/CmsBaseAdminBundle/Controller/JavascriptController.php).

Extending to Other Cloud Providers

If additional cloud providers (e.g., Google Cloud Storage) need to be integrated in the future, a new storage handler (e.g., StorageGcp) should be created.

This new handler must implement the following methods with provider-specific logic:

• uploadFile
• deleteFile
• promoteTemporaryFile

This approach ensures flexibility and scalability when adding new storage options.

Local Upload

The local upload process is handled by the file:

Wf/Bundle/MediacenterBundle/Resources/public/javascripts/media/storage_local.js.

This file manages local storage operations by making requests to a set of endpoints configured in:

Wf/Bundle/MediacenterBundle/Controller/MediaController.php.

These endpoints, in turn, utilize the Wf/Bundle/MediacenterBundle/Services/UploadService.php to handle the internal logic for file uploads in local development environments.

S3 Upload

The S3 upload process is managed by the file: Wf/Bundle/MediacenterBundle/Resources/public/javascripts/media/storage_s3.js .

Unlike the local upload, the S3 upload is performed client-side using the AWS SDK for JavaScript. When initiating any operation against AWS, an S3 client is configured (configureS3Client), which retrieves temporary credentials and enables direct operations using new AWS.S3().

Obtaining Credentials with the STS Service

During the file upload process with storage_s3, temporary credentials are obtained via AWS STS. In this case, credentials are not directly fetched using the JavaScript SDK. Instead, a request is made to the backend PHP server (via the endpoint wfcm_mediacenter_get_aws_token), which returns a JSON response containing the temporary credentials.

For detailed documentation on AWS STS requests, refer to: AWS STS - Desarrollo con LocalStack.

Cleaning Temporary Files

The command Wf/Bundle/MediacenterBundle/Command/DeleteOldTempFilesCommand.php is responsible for removing residual temporary files that are older than 5 days. It can be executed with the following command:

app/admin/console wf:cms:mediacenter:remove-temp-files

Future Improvements

• AWS SDK upgrade from v2 to v3
• Replacing the upload process from the news section to include the Mediacenter view