cloakwp/media-orientation

Filter the WordPress media library by portrait, landscape, or square orientation.

dev-main 2026-08-28 16:32 UTC

Requires

• php: >=8.2
• cloakwp/core: dev-main
• composer/installers: ^1.0 || ^2.2

Requires (Dev)

• phpunit/phpunit: ^11.0 || ^12.0

LGPL-3.0-only

• Kaelan Smith

Published on Packagist.org on 2026-09-01 00:06 UTC

README

Filter the WordPress media library by Portrait, Landscape, or Square. Feels like WordPress core — configured in PHP, no settings UI, no admin notices.

An image or video is square when its width and height are within 5% of each other (overrideable). Dimensions come from attachment metadata; the derived value is stored as post meta so filtering stays a cheap meta_query.

Install paths

1. Composer (must-use plugin) — recommended

composer require cloakwp/media-orientation

Requires cloakwp/core (pulled in automatically). Package type is wordpress-muplugin. With composer/installers configured, that installs to:

wp-content/mu-plugins/media-orientation/

(Your project may map that path differently — e.g. Bedrock uses public/app/mu-plugins/.)

Important: WordPress core only auto-loads PHP files directly in mu-plugins/. It does not load plugins nested in subdirectories like mu-plugins/media-orientation/media-orientation.php. You need an autoloader (or a tiny stub) for subdirectory must-use plugins.

Recommended: Roots Bedrock Autoloader — it scans mu-plugins/*/*.php for plugin headers and includes them. Ships with Bedrock; usable in any WordPress project as roots/bedrock-autoloader. Once loaded, this package shows under Plugins → Must-Use (not the toggleable Plugins list).

Without an autoloader, add a one-line stub at the mu-plugins root:

<?php
// wp-content/mu-plugins/media-orientation-loader.php
require WPMU_PLUGIN_DIR . '/media-orientation/media-orientation.php';

Optional fluent config in your theme functions.php (runs before the deferred default boot):

use CloakWP\MediaOrientation\MediaOrientation;

MediaOrientation::make()
  ->squareTolerance(0.05)
  ->register();

If you never call register(), the plugin bootstrap starts with defaults on init priority 1.

2. Traditional plugin install (download as a zip)

For sites that don’t use Composer — install it like any other WordPress plugin. This plugin requires cloakwp/core on the site (Composer is the straightforward way to get both).

1. Open the GitHub repository page.
2. Click the green Code button, then Download ZIP.
3. Unzip the file. You’ll get a folder named something like cloakwp-media-orientation-main.
4. Rename that folder to media-orientation (optional but keeps the Plugins list tidy).
5. Install it in either way:
   • WordPress admin: Plugins → Add New → Upload Plugin → choose the zip (re-zip the renamed folder if you renamed it) → Install Now → Activate, or
   • Manually: upload the media-orientation folder into wp-content/plugins/ on your server (via FTP/SFTP or your host’s file manager), then go to Plugins and click Activate.

Same defaults as the Composer path. Developers can still override config via fluent register() or the config filter (below). No mu-plugin autoloader needed.

Fluent API

MediaOrientation::make()
  ->squareTolerance(0.05)   // default; `5` also means 5%
  ->metaKey('_media_orientation')
  ->register();

Config filter

add_filter('cloakwp/media-orientation/config', function ($config) {
  return $config->withSquareTolerance(0.08);
});

Admin features

• List view: All orientations / Portrait / Landscape / Square dropdown on the media filter bar
• Grid / media modal: the same dropdown (including ACF Image, Gallery, and File field pickers)

Audio, PDFs, and other files without width/height are omitted when an orientation is selected.

Data model

Stores _media_orientation (portrait | landscape | square) on attachments. Written when metadata is generated or updated, and backfilled in short batches the first time you open the Media Library (or a media modal). Changing squareTolerance triggers a reindex.

No custom tables, no options UI that saves config to the database (configure via PHP).

Square test: abs(width - height) / max(width, height) <= tolerance.

Architecture

Uses CloakWP\Core\Media\LibraryFilter for the Media Library UI and query. This package only classifies dimensions and stores meta.

src/Core/              # Config, Classifier
src/Plugin/            # Indexer + LibraryFilter registration
MediaOrientation.php   # Fluent facade

Development

composer install
composer test

License

LGPL-3.0-only