README

License: GNU GPL, Version 2

Repository: https://gitlab.sgalinski.de/typo3/sg_video

Please report bugs here: https://gitlab.sgalinski.de/typo3/sg_video/-/issues

Overview

sg_video is the unified successor for sg_youtube and sg_vimeo.

It provides one TYPO3 content element (tt_content.CType = sgvideo_video) with a provider switch:

• YouTube
• Vimeo
• Custom (local TYPO3/FAL video files)

For migrated YouTube/Vimeo records, frontend behavior and look/feel are aligned with the legacy extensions. The main namespace change for integrators is:

• sg-youtube / sg-vimeo -> sg-video

Requirements

• TYPO3: ^13.4 || ^14.0
• PHP: 8.3+

Installation

Composer

composer require sgalinski/sg-video

TYPO3 integration

1. Activate sg_video in TYPO3 Extension Manager.
2. Include static TypoScript: SG Video (EXT:sg_video/Configuration/TypoScript).

Configuration

Credentials are configured via TypoScript constants:

plugin.tx_sgvideo.settings.providers.youtube.apiKey = <key>
plugin.tx_sgvideo.settings.providers.vimeo.clientId = <id>
plugin.tx_sgvideo.settings.providers.vimeo.clientSecret = <secret>
plugin.tx_sgvideo.settings.providers.vimeo.personalAccessToken = <token>

Environment fallback keys (read directly by providers):

• SG_VIDEO_YOUTUBE_API_KEY
• SG_VIDEO_VIMEO_PERSONAL_ACCESS_TOKEN
• SG_VIDEO_VIMEO_CLIENT_ID
• SG_VIDEO_VIMEO_CLIENT_SECRET

website_base/project_theme style env wiring

If you already use existing website_base variables, map them in your project TypoScript:

plugin.tx_sgvideo.settings.providers.youtube.apiKey := getEnv(SITE_WEBSITE_BASE_SGYOUTUBEAPIKEY)
plugin.tx_sgvideo.settings.providers.vimeo.clientId := getEnv(SITE_WEBSITE_BASE_SGVIMEOCLIENTID)
plugin.tx_sgvideo.settings.providers.vimeo.clientSecret := getEnv(SITE_WEBSITE_BASE_SGVIMEOCLIENTSECRET)

Usage

Add content element sgvideo_video and configure:

• provider: youtube|vimeo|custom
• source kind:
  • YouTube: video|channel|playlist
  • Vimeo: video|channel|showcase
  • Custom: file
• source identifier / file reference

Available frontend layouts:

• default
• rows
• playlist

Implemented behavior includes:

• unified filters (searchTerm, duration)
• read-more / read-less behavior
• lightbox and no-lightbox behavior parity
• structured data JSON-LD output via StructuredVideoDataViewHelper

For custom/local videos:

• files are resolved from settings.fileReference relation first
• sys_file_reference.autoplay is respected in lightbox and inline no-lightbox rendering

Caching and cache bypass

Provider responses use cache sgvideo_cache (24h TTL for provider responses).

Supported URL parameters for bypassing provider cache:

• canonical: disableSgVideoCache=1
• legacy aliases:
  • disableYoutubeCache=1
  • disableVimeoCache=1

HTTP request behavior

Provider HTTP calls use explicit timeout settings:

• connect timeout: 2s
• request timeout: 8s

Retry/backoff is intentionally not enabled in this release.

Events

sg_video exposes the unified event lifecycle:

• SGalinski\SgVideo\Event\BeforeProviderCallEvent
• SGalinski\SgVideo\Event\AfterProviderCallEvent
• SGalinski\SgVideo\Event\AfterFilterVideosEvent
• SGalinski\SgVideo\Event\AfterMapCustomThumbnailsEvent

Migration from sg_youtube / sg_vimeo

Migration is handled by TYPO3 upgrade wizard:

• wizard id: sgvideo_contentElementMigration
• migrates legacy CType and legacy list_type records to sgvideo_video
• maps legacy FlexForm schema to sg_video
• migrates legacy thumbnail relation field names to settings.thumbnailImages

Template override note:

• sg_video uses one unified template entrypoint (Video/Index.html).
• Provider-specific template overrides are no longer split by tx_sgyoutube / tx_sgvimeo.
• Existing custom Vimeo/YouTube templates must be migrated manually to the sg_video template contract.

Rector/Fractor migration tooling is intentionally de-scoped for this release. The TYPO3 upgrade wizard is the canonical migration path.

See detailed integrator steps in UPGRADE.md.

Non-composer installations

No Vimeo SDK package or PHAR fallback is required.

sg_video uses direct HTTP requests (RequestFactory) for Vimeo API access, so the following are not required:

• vimeo/vimeo-api
• Libraries/vimeo-api.phar

Frontend assets (sgc)

Build assets from extension root:

npm install

Note:

• The lightbox dependency is vendored in Resources/Public/JavaScript/Modules/Vendor/BasicLightbox/.
• sgc build does not require extension-local node_modules/basiclightbox.

If you work inside a website_base monorepo with sgc:

./sgc-core/core/sgc build --ext sg-video

For watcher-based frontend development in website_base, also update .sgc-config.js:

• add sg-video to extensions
• add sg-video to watchExtensions
• add these JS libraryPaths entries:
  • ./vendor/sgalinski/sg-video/Resources/Public/JavaScript/Modules
  • ./vendor/sgalinski/sg-video/Resources/Public/JavaScript

Generated minified assets in Resources/Public/JavaScript/Dist/ and Resources/Public/StyleSheets/ are shipped and versioned.

Testing

Run from website_base project root (monorepo usage):

composer ecs vendor/sgalinski/sg-video
composer phpstan local/sg_video
vendor/bin/phpunit --configuration local/sg_video/phpunit.xml.dist