mhinspeya / mhinspeya-hyva-vimeogallery

1.0.0 2026-08-27 07:37 UTC

Requires

• php: >=7.2.0
• magento/framework: *
• magento/module-backend: *
• magento/module-config: *
• magento/module-store: *
• mhinspeya/backend-mod: ^1.0

GPL-3.0

• MHinspeya

Published on Packagist.org on 2026-08-27 07:39 UTC

README

mhinspeya/mhinspeya-hyva-vimeogallery

Magento 2 / Hyvä module that displays videos from a Vimeo channel on the storefront, with admin design controls, maximum video limit, ASC/DESC date sorting, license validation, short-lived API caching, and LiteMage-friendly AJAX loading.

Table of contents

• Requirements
• Features
• Installation
• Configuration
• License
• Vimeo setup (sample)
• Frontend usage
• Embed on a CMS page
• Frontend routes & AJAX
• Caching & LiteMage
• Admin refresh
• CLI diagnostics
• Troubleshooting: works locally, fails on server
• Exception handling & logging
• Translations (i18n)
• PHP compatibility
• Uninstall
• Post-install commands
• Support
• User Guide (step-by-step)

Requirements

Dependency	Notes
Magento 2.4.x	Tested with Magento 2.4.8
PHP >= 7.2	Compatible through current PHP 8.x
Hyvä Theme	Storefront uses Alpine.js AJAX loading
mhinspeya/backend-mod	Required (^1.0) for Inspeya admin menu / tab
Vimeo account	Channel + personal access token with channel video read scope

Features

Storefront

• Gallery page at /vimeogallery
• Optional embed on any CMS page via {{block}}
• Live video list via AJAX (page shell can be LiteMage / FPC cached)
• Responsive video grid with Vimeo embeds (fullscreen supported by the player)
• Load more button (chunk size + button styles configurable in admin)
• Maximum Videos limit (e.g. show only the latest 5)
• Video Sort Order by date: newest first (DESC) or oldest first (ASC)
• Gallery title + title / video-name colors from admin
• Disabled state notice when the module is turned off

Admin

• License key validation (same Inspeya license service as Popup)
• Enable / disable module
• Vimeo access token (encrypted) + channel ID (URL paste supported)
• Refresh video list now (clears only the Vimeo list cache, not Magento FPC / LiteMage)
• Gallery design colors (color picker)
• Load more: videos per page (dropdown), maximum videos (numeric), sort order (ASC/DESC), button text & styles
• Menu: Inspeya → Vimeo Gallery → Configuration
• CLI: bin/magento vimeogallery:test-api

Installation

* For production environments, prefer your normal deploy flow. Use --keep-generated only when appropriate.

Type 1: Manual (Zip / app code)

1. Extract / copy the module to:

    app/code/MHinspeya/VimeoGallery
   

2. Ensure mhinspeya/backend-mod (MHinspeya_BackendMod) is installed.
3. Enable and upgrade:

php bin/magento module:enable MHinspeya_BackendMod MHinspeya_VimeoGallery
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush

Type 2: Composer

1. Add the Inspeya repository (if not already configured):

composer config repositories.inspeya composer https://repo.inspeya.com/

1. Require the package:

composer require mhinspeya/mhinspeya-hyva-vimeogallery

1. Enable and upgrade:

php bin/magento module:enable MHinspeya_BackendMod MHinspeya_VimeoGallery
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush

Verify module status

php bin/magento module:status MHinspeya_VimeoGallery

Expected: Module is enabled.

Configuration

Admin path:
Stores → Configuration → MHinspeya.de → Vimeo Gallery
(or Inspeya → Vimeo Gallery → Configuration)

Section ID: vimeogallery

Use scope Default Config unless you intentionally configure per website/store.
On a new server, re-paste the access token (do not copy encrypted values from another Magento install).

1. License Key

Field	Path	Description
License Key	vimeogallery/license/license_key	Required. Validated against Inspeya license API. Green / red icon in admin.

2. General Configuration

Field	Path	Default	Description
Enable Module	vimeogallery/general/enabled	No (0)	Turns storefront gallery on/off
Vimeo Access Token	vimeogallery/general/access_token	—	Personal access token (stored encrypted)
Vimeo Channel ID	vimeogallery/general/channel_id	—	Channel ID/slug, or full channel URL (ID is extracted). Not Showcase/Album.
Channel Video List	—	—	Shows cached/live count + Refresh video list now

3. Gallery Design

Field	Path	Default	Description
Gallery Title	vimeogallery/design/gallery_title	Vimeo Channel Videos	Centered heading above the grid
Title Color	vimeogallery/design/title_color	#111827	Heading color
Video Name Color	vimeogallery/design/video_name_color	#111827	Title under each video

4. Load More Button

Field	Path	Default	Description
Videos Per Page	vimeogallery/loadmore/videos_per_page	9	Initial count + each Load more click (dropdown: 3–48)
Maximum Videos	vimeogallery/loadmore/max_videos	0	Numeric text field. Total videos on storefront. 0 = no limit (max 500). Example: 5 = only first 5 in the chosen sort order.
Video Sort Order	vimeogallery/loadmore/sort_direction	desc	Newest first (DESC) or Oldest first (ASC) by Vimeo date
Button Text	vimeogallery/loadmore/button_text	Load more videos	Button label
Background Color	vimeogallery/loadmore/background_color	#111827	Button background
Text Color	vimeogallery/loadmore/text_color	#ffffff	Button text
Border Color	vimeogallery/loadmore/border_color	#111827	Button border
Border Width	vimeogallery/loadmore/border_width	1px	CSS size
Line Height	vimeogallery/loadmore/line_height	1.2	CSS line-height

How Maximum Videos + Videos Per Page + Sort work together

Setting	Role
Video Sort Order	Order returned by Vimeo (sort=date&direction=asc\|desc)
Maximum Videos	Hard cap on how many videos the storefront receives (after sort)
Videos Per Page	How many of those are shown at once; Load more reveals the next chunk

Example: Sort = Newest first (DESC), Maximum Videos = 5, Videos Per Page = 3
→ Shows the 3 newest, then Load more once to show all 5, then Load more hides.

Design / Load more style values are delivered via the AJAX JSON payload so storefront updates do not require clearing LiteMage for those settings.
After changing sort order or channel content, use Refresh video list now (or wait ~60s for cache TTL).

License

Same flow as MHinspeya Popup:

1. Enter the license key and Save Config.
2. Valid key → success message; merchant can set Enable Module to Yes/No.
3. Invalid / empty / expired / wrong-domain key → module is force-disabled (enabled = 0).

Default: module is disabled until you enable it (after a valid license is stored).

Vimeo setup (sample)

1. Create a channel

In Vimeo: create or open a Channel and note the channel ID (example: 1969845).

Use a Channel ID, not a Showcase / Album ID.

2. Create an access token

1. Vimeo Developer → Apps → your app → Generate an access token
2. Scopes must allow reading channel videos
3. Paste the token into Magento Vimeo Access Token and save

3. Add videos to the channel

Videos must be added to the channel.
Uploading to the Vimeo library alone is not enough — the gallery reads /channels/{id}/videos.

4. Geographic privacy (servers)

If Magento is hosted in another country, allow that region in Vimeo channel/video geographic privacy.
Otherwise Vimeo may return error 5451 (restricted in your region) even with a valid token.

5. Sample Magento config values

Setting	Sample
License Key	Your purchase key (or internal key for local)
Enable Module	Yes
Channel ID	1969845
Access Token	xxxxxxxx… (your token)
Videos Per Page	9
Maximum Videos	0 (unlimited) or 5 (only five)
Video Sort Order	Newest first (DESC)

6. Open the gallery

https://your-store.example/vimeogallery

Local example:

http://localhost/magento248/pub/default/vimeogallery

Frontend usage

1. Open /vimeogallery
2. Videos load via AJAX (ordered by admin Video Sort Order)
3. List is capped by Maximum Videos (if set)
4. First chunk shows (admin Videos Per Page)
5. Click Load more for the next chunk (until the max is reached)
6. Use the Vimeo player fullscreen control on each embed

Embed on a CMS page (or any CMS content)

You can place the gallery on any CMS page, block, or page builder content using Magento’s {{block}} directive:

{{block class="MHinspeya\VimeoGallery\Block\ChannelVideos" name="vimeo.gallery.cms" template="MHinspeya_VimeoGallery::videos.phtml"}}

Steps (Admin):

1. Go to Content → Pages → Add New Page (or edit an existing page)
2. Set Page Title and URL Key (e.g. vimeo-gallery-test)
3. In the content editor (HTML / Page Builder HTML), paste the {{block}} directive above
4. Enable the page, assign store views, and Save
5. Open the page URL, e.g. https://your-store.example/vimeo-gallery-test

Local example:

http://localhost/magento248/pub/vimeo-gallery-test

The block loads the same AJAX gallery UI and CSS as the dedicated /vimeogallery route. Module must be enabled and configured (channel ID + access token).

More detail + screenshots: docs/user-guide/USER_GUIDE.md

Frontend routes & AJAX

Type	Path	Description
Page	/vimeogallery	Gallery page (cacheable shell)
AJAX GET	/vimeogallery/ajax/videos	JSON: videos + design tokens

AJAX payload includes design tokens (videos_per_page, max_videos, sort_direction, colors, button styles, etc.).

Caching & LiteMage

Layer	Behavior
Gallery HTML page	Cacheable (LiteMage / Magento FPC friendly)
AJAX /vimeogallery/ajax/videos	Not cached (Cache-Control + X-LiteSpeed-Cache-Control: no-cache)
Vimeo API list	Magento app cache ~60 seconds; separate cache keys per channel and sort direction (asc/desc)
Stale fallback	If Vimeo returns 429 / errors, last good cached list may be served

Optional LiteMage exclude (safety):

/vimeogallery/ajax/videos

API fetch supports Vimeo paging (up to 100 videos × 5 pages = 500), then Maximum Videos can trim further for the storefront.

Admin refresh

Refresh video list now (in General Configuration):

• Clears Vimeo channel video cache keys (both ASC and DESC variants)
• Re-fetches from Vimeo immediately with the current Video Sort Order
• Does not flush Magento FPC, config cache types broadly, or LiteMage

Use after:

• Adding/removing videos on the Vimeo channel
• Changing Video Sort Order
• When you need an instant update instead of waiting ~60 seconds

CLI diagnostics

php bin/magento vimeogallery:test-api

Prints the channel ID Magento is using, token length / last 4 characters, HTTP status, and a response preview.
Useful when local works but the server fails (compare token_ends and channel_id).

Troubleshooting: works locally, fails on server

If admin refresh / CLI returns HTTP 404 with Vimeo body:

"This resource is restricted in your region." (error_code 5451)

this is not a Magento token/channel bug. Vimeo geo-blocks the channel for the server’s country/IP.

Fix in Vimeo (channel / video privacy → geographic restriction): allow the country where Magento is hosted, or disable region lock.

Other common cases:

Symptom	What to do
Token missing / decrypt error	Re-paste token under Default Config on that server
HTTP 401 / 403	New token with channel video read scope
HTTP 404 (real “not found”)	Wrong Channel ID, or Showcase ID instead of Channel
HTTP 429	Wait and refresh again

Exception handling & logging

• Token decrypt failures → token treated as missing
• Vimeo HTTP / JSON / curl failures → logged; empty or stale-cache fallback
• Region restriction (5451) → clear admin message
• Magento cache read/write/clear failures → logged, non-fatal
• AJAX / admin refresh exceptions → safe JSON error message for the UI

Look for log lines prefixed with:

MHinspeya_VimeoGallery

in var/log/system.log / var/log/exception.log.

Translations (i18n)

Included locale packs:

Locale	File
en_US	i18n/en_US.csv
de_DE	i18n/de_DE.csv
de_AT	i18n/de_AT.csv
de_CH	i18n/de_CH.csv

Covers admin labels/comments, storefront strings, license messages, and API/refresh errors.

After deploy:

php bin/magento cache:flush

(and static content deploy when required for your mode).

PHP compatibility

Constraint	Value
composer.json	"php": ">=7.2.0"
Coding style	Magento2 PHPCS; no PHP 8-only syntax required

Uninstall

php bin/magento module:disable MHinspeya_VimeoGallery
php bin/magento setup:upgrade
php bin/magento cache:flush

Then remove app/code/MHinspeya/VimeoGallery (or uninstall the Composer package).

Config values under vimeogallery/* may remain in core_config_data until cleaned manually if desired.

Post-install commands

php bin/magento module:enable MHinspeya_VimeoGallery
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush

Support

• Package: mhinspeya/mhinspeya-hyva-vimeogallery
• Vendor: MHinspeya / Inspeya
• Contact: [e-mail]
• License: GPL-3.0
• User guide: docs/user-guide/USER_GUIDE.md