Download the PHP package belisoful/prado-publishing without Composer

prado-publishing

TPublishingManager for Prado: a TAssetManager that publishes files through asset objects, so behaviors can rename, virtualize, block, compress, and process them, including image resizing, format conversion, and image metadata preservation and scrubbing.

TPublishingManager extends TAssetManager and keeps all of its features: the base path and URL, the hashed publishing directories, the publishing options (only, except, caseSensitive, beforeCopy, afterCopy, forceCopy, atomic), atomic writes, directory completion markers, symlinked assets, timestamps, the asset map, and tar publishing options. What it replaces is how a file gets written. TAssetManager copies it. TPublishingManager instances it as an IAsset, lets the asset's behaviors act on it, and writes the result through the same atomic, marker, and permission handling. A file with no behaviors publishes byte for byte, to the same URL TAssetManager would give it, and the framework's TAssetManagerTest passes against TPublishingManager.

Usage

Replace the application's asset manager module:

Then attach behaviors to the asset classes. This fingerprints scripts and stylesheets for cache busting, and serves them gzip-compressed:

This publishes photos upright, at most 1920×1080, as JPEGs, keeping their metadata but removing the location and camera serial number:

How a file publishes

Every route goes through one asset router, TPublishingManager::routeAsset(): a string path, an IAsset object, each file of a published directory, and a tar archive from publishTarFile().

1. Discovery. A string path is instanced as TFileAsset, or as TImageAsset for an image extension. onDiscoverClass handlers (such as TAssetDiscovery) can route it to another class first.
2. Path. The asset resolves its file path through the dySetAssetFilePathPre, dySetAssetFilePathPost, and dyRewriteFilePath dynamic events. Behaviors virtualize a path onto a real file (TAssetVirtualize), or cancel publishing (TAssetBlocker). Then dyAlterAssetFilePath gives the published file name: format conversions change the extension, TAssetCacheBuster adds a fingerprint, and TAssetCompress appends .gz. The published location is the TAssetManager hashed directory of that path.
3. Write. The asset writes itself to a temporary file and raises onProcessAsset on it. Image behaviors process the file there, and finalizers (image saving, then gzip) run in priority order. The file then moves into place, so a reader never sees it half processed. Only an unchanged copy with Atomic off is written in place. A failed write publishes nothing.

A directory publishes with the TAssetManager directory walk and completion marker (its copyDirectoryFile() hook), but each file in it publishes as its own asset, under its name with its behaviors' rename applied, and with the caller's atomic option. A renamed file never takes the name of another file in its folder: when logo.jpg converts to PNG beside a real logo.png, it publishes as logo.jpg.png, and logo.png keeps its name.

The published location comes from the TAssetManager hooks: virtualAssetPath() gives the asset's publish path and copyDirectoryFile() publishes each file of a directory. An asset resolves that path through its behaviors on every read, so CacheAssetPublishFilePath="true" on the manager has the assets it instances resolve it once instead (TAsset::CachePublishFilePath). It is off by default: a behavior that renames a file from data it changes itself, without resetting the asset's file path cache, would keep its first name.

Renaming behaviors and directories. A behavior that renames files (TAssetCompress, TAssetCacheBuster, the format conversions) renames the files of every published directory it matches, including the framework's own script and style packages, whose URLs are built from the directory URL. Scope such behaviors with MatchFiles, or attach them to TImageAsset for images. PublishOriginalNames="true" also publishes each renamed file unprocessed under its own name, so those URLs resolve; the original is the unprocessed source, so leave it off when the processing matters, such as scrubbing image metadata.

A tar archive publishes as a TTarAsset, extracted by TTarFileExtractor into the directory, with the extractor's options on the asset. An archive with a checksum file publishes to the TAssetManager directory of its folder; one without publishes to a directory of its own. An entry that a TAssetBlocker of the archive's asset would block is not extracted. A published IPublishedCapture asset receives its path and URL.

With LinkAssets, a file is symlinked only when its asset writes the source unchanged (TAsset::getIsPassThrough(): not a converting asset such as TGDFAsset, no class that overrides the write, and no behavior taking over the write), keeps its name, and has no onProcessAsset handlers. Any other file is written, because a link would serve the unprocessed source, and a link published before is replaced by the file. An asset class with a processing behavior attached, even one that does not match the file, is therefore copied rather than linked.

Contents

The classes keep their framework namespaces, Prado\Web and Prado\Web\Assets.

Manager and assets

Behaviors (Prado\Web\Assets\Behaviors)

Image filters (<filter type="...">)

AutoCrop, Blur, BoxBlur, CircleMask, Convolution, GammaCorrect, Image (watermark), MetaData, Orient, Rectangle, Resize, Text (watermark), and the GD imagefilter effects by name (Grayscale, Negate, Brightness, Contrast, Colorize, EdgeDetect, Emboss, GaussianBlur, SelectiveBlur, MeanRemoval, Smooth, Pixelate, Scatter). A filter can also be given by class, and filters can be kept in a separate file with the imager's FilterFilePath (its filters follow the imager's, and its <metadata> attributes override the imager's).

Filters are not behaviors. An imager's configuration is parsed once into filter specifications (Filters\TImagerFilterFactory) shared by every asset the imager attaches to, and the filter objects are created only when the imager first processes a matching image (in Debug mode, when it attaches, so configuration errors show early). They run in configuration order. A filter implements Filters\IBaseImagerFilter (getEnabled(), getGraphicsMode(), and filterImage(&$image, $param)), usually by extending Filters\TBaseImagerFilter and writing filterGdImage(), filterImagickImage(), or both; $param is the publishing TAssetEventParameter, which holds the asset, the image types, and the image metadata (getImageMetaData()). Register a type name for your own filter:

Register types before the configuration that uses them is parsed; a registered type takes precedence over a built-in type of the same name. In code, addFilter(), removeFilter(), getFilter(), and getFilters() on an imager edit and read its filters. Two filters with one name, or a type with a property that contradicts it, are configuration errors.

Image sizes are limited at both ends. An imager's MaximumPixels (default 50 megapixels) rejects an image whose declared size is larger before it is decoded, so a small file cannot expand into gigabytes of memory. A filter's MaximumOutputPixels (the same default) rejects a Resize, Image, or Text configuration that would make a larger image. 0 turns either limit off.

Graphics libraries

An imager reads the image with GD, then Imagick, and falls back to the prado-image container for a format neither decodes (TIFF). A filter implements filterGdImage(), filterImagickImage(), or both, and getGraphicsMode() follows from that: a filter of one library gets the image in that library, and a filter of both, or one that overrides filterImage() itself, runs in whichever library the image is already in. The imager converts between them through a lossless PNG, which keeps the alpha channel, and leaves the image there for the filters that follow, so a chain can mix both libraries freely. A filter whose library is not installed is skipped.

The two libraries do not produce identical pixels. Orient, GammaCorrect, Rectangle, Negate, Brightness, MeanRemoval, and Smooth match GD exactly or to within a unit of rounding; Convolution is within one unit per channel; the rest are equivalent rather than identical, and each class documents what differs — the resampling kernels of Resize, the anti-aliased edge of CircleMask, the blur radii, and the effects whose arguments mean different things in the two libraries (Contrast, Colorize, EdgeDetect, Emboss).

The image is written back with GD where it can be (and with the saving properties, which are GD work), by the prado-image containers for GIF and TIFF, and by the graphics library for JPEG, PNG, and WebP when GD is missing. A format conversion only renames the published file when the image can be written in that format (canEncode()), so a file is never published under a name whose format it is not; such an image publishes unprocessed, while an image that fails to encode or to write throws, rather than publishing the bytes from before the processing.

Image metadata

Image metadata is read and written with belisoful/prado-image for JPEG, PNG, WebP, GIF, and TIFF. When an imager processes an image, the metadata is read before the image is re-encoded, and it is written into the encoded image, so the published file is written once:

• Preserved carriers are chosen with MetaDataPreserve: any of EXIF, IPTC, XMP, Color (the ICC profile), or All (the default) or None. A carrier the published format cannot hold is dropped: GIF has no EXIF, and GIF and WebP have no IPTC. A TIFF keeps its image structure tags, and the preserved EXIF is written into its directory. BMP, WBMP, and XBM have no prado-image container and publish without metadata. None also removes comments, PNG text chunks, and data after the end of the image.
• Scrubbed identifying information is chosen with Scrub, by TPrivacyCategory: e.g. Location, Author, SerialNumber, Timestamp, Identity, Provenance, All. A scrub also removes data after the end of the image, such as the secondary images of a JPEG (MPF), and Author removes XMP face regions. When several imagers match one image, their scrubs combine and only the carriers every one of them preserves are kept. A scrub that cannot be written throws rather than publishing the unscrubbed image.
• Updated: the EXIF and IPTC dimensions follow a resized image, an EXIF thumbnail is regenerated (ExifThumbnail*), JPEGs get the JFIF header and optional thumbnail selected by JFIFMode (None, JFIF, Thumbnail, JFXXJPEG, JFXXPalette, JFXXColor, JFXXEfficiency), and IPTCPublishEncoding sets the IPTC character set.

• Edited: the Orient filter rotates the image upright and records the upright orientation, and the MetaData filter writes fields:

  When no filter changes the pixels and no conversion property (such as ImageQuality) is set, only the metadata is rewritten; the encoded image data is kept as it is.

• Matched: an imager's MetaMatch limits it to images whose metadata matches, e.g. MetaMatch="Keywords=portfolio" or MetaMatch="EXIF:Model==X100V".

Field names are IPTC dataset names or ids (Keywords, 2#025), EXIF tag names (Artist), or carrier-prefixed names (IPTC:Copyright, EXIF:Copyright, XMP:dc:title).

Prado integration

The package is a Composer Prado extension ("type": "prado4-extension"), and its config/ directory holds its declarative configuration:

Prado 4.4 loads both for every installed extension that declares them in extra.prado, before any module initializes, so an application does not wire them:

Outside a Prado application, or to load them by hand, they are a class map and a message file:

The class map lets configuration use short names such as Class="TAssetJPEGize". Unregistered messages still carry their key, so registration affects readability, not behavior.

Requirements

• PHP 8.2+
• pradosoft/prado 4.4 (^4.4@dev until 4.4.0 is released)
• belisoful/prado-image
• ext-gd for images, and ext-imagick for the formats and filters GD cannot do; ext-dom for XMP; ext-zlib for gzip and deflate; ext-brotli or ext-zstd for those codings, or the command-backed codecs of belisoful/prado-compression

Install

Prado 4.4 has no stable release yet, so this package requires pradosoft/prado: ^4.4@dev, and the stability flag of a dependency does not carry to the project installing it. A project that does not already allow development versions of Prado needs them:

prefer-stable keeps every other dependency on its stable release.

Test

TPublishingManager must stay a drop-in replacement for TAssetManager, so the suite runs the framework's own TAssetManagerTest against it, loaded from the installed pradosoft/prado package, with no test skipped. The package's own tests cover the manager's asset publishing, the asset classes, every behavior and filter, and the image metadata, on real image files.