Download the PHP package develate/blogframe without Composer

Blogframe by develate

Blogframe is a Laravel package for blogs whose articles live in version-controlled Markdown files. It discovers translated articles, parses YAML front matter, renders CommonMark with runtime custom tags, and serves local images through signed responsive-image URLs.

Blogframe is deliberately a content package: your application keeps control of article routes, controllers, Blade views, feeds, and presentation.

Requirements

• PHP 8.2 or newer
• Laravel 12 or 13
• GD or Imagick for responsive image generation

Installation

Install the package with Composer:

Laravel discovers BlogframeServiceProvider and the Blogframe facade automatically. Publish the configuration when you need to change the defaults:

Article structure

Articles belong in the host application's resources/blog/articles directory. The directory name supplies the positive numeric ID and name; the Markdown filename supplies the language:

Every translation requires YAML front matter with a non-empty title and image. Other attributes are preserved:

The following front-matter keys are reserved because Blogframe derives them: id, name, language, image_url, image_srcset, image_sizes, markdown, html, and source_path.

Invalid filenames, duplicate IDs or translations, malformed YAML, missing required attributes, and missing images throw a descriptive Blogframe exception instead of silently hiding content.

Querying articles

Use the facade from controllers, view models, commands, or application code:

all() returns an Illuminate\Support\Collection ordered by descending article ID. If no language is supplied, Blogframe uses Laravel's current locale. When a translation is unavailable it tries the configured fallback language, which defaults to app.fallback_locale.

An article is an immutable object with these public properties:

markdown contains only the body after front matter has been removed. html and toHtml() contain the rendered CommonMark output.

Header and OG images

imageUrl is the signed original image URL and is suitable for Open Graph metadata:

For a responsive header, add the generated candidate list and sizes:

You can also generate image values directly:

The image custom tag

The built-in image tag resolves images relative to resources/blog/images:

With local image serving enabled, the result contains:

• a signed fallback src near the configured fallback width;
• a signed srcset containing only candidates that do not upscale the source;
• sizes="100vw" by default, overridable with the tag's sizes attribute;
• intrinsic width and height, unless explicitly provided.

The tag accepts src, alt, class, id, title, width, height, loading, decoding, fetchpriority, role, sizes, data-*, and aria-*. Blogframe generates srcset; an authored srcset, positional argument, event handler, style, or unknown attribute is rejected. Attribute values are HTML-escaped.

Registering custom tags

Additional tags are registered at runtime, not in configuration. Register them in your application's AppServiceProvider::boot() method:

The identifier returned by the tag is its registry key. A later registration with the same identifier replaces the existing tag and invalidates rendered articles in the current lifecycle:

The built-in image tag follows the same rule and can be replaced by registering another tag whose identifier is image.

Custom tags extend Develate\CommonmarkCustomtags\Customtag. See develate/commonmark-customtags for its argument syntax and interface.

Configuration

The published config/blogframe.php contains all supported settings:

Configured CommonMark extension classes are resolved through Laravel's container. Blogframe always owns the single CustomtagExtension; register individual tags with Blogframe::customtag() instead of configuring another custom-tag extension.

Use Intervention\Image\Drivers\Imagick\Driver when Imagick is installed and preferred. An allowed source format must also be supported by the selected driver. SVG is intentionally unsupported.

Signed responsive image routes

When images.serve is enabled, Blogframe registers this named route:

Every URL has a permanent relative Laravel signature. The source fingerprint, requested width, and path are covered by that signature. The route additionally rejects widths outside the configured allowlist, upscaling, stale fingerprints, unsupported files, and paths that leave the configured image directory.

Relative signature validation allows the generated URLs to pass through a proxy or CDN host without weakening path validation. Public URLs are absolute so they can be used for Open Graph metadata.

Derivatives are generated proportionally on their first request, retain the source format, and are cached beneath images.cache_path. A per-variant file lock and atomic rename protect concurrent first requests. The source fingerprint changes when the source contents change, giving new URLs and making the default one-year immutable cache header safe. Old derivative directories may be removed during normal deployment cleanup.

When images.serve is false, Blogframe registers no image route and generates no srcset. Set images.base_url to the public directory or CDN containing the same relative image paths:

Exceptions

• ArticleNotFoundException is thrown by findOrFail().
• InvalidArticleException describes invalid article files or rendering failures.
• InvalidImageException describes unsafe, missing, or unsupported images.
• InvalidConfigurationException describes inconsistent package configuration.

The signed image route intentionally translates invalid image requests to HTTP 404 responses; Laravel's signature middleware returns HTTP 403 before image processing when a signature is missing or modified.

Testing

The test suite uses Orchestra Testbench and covers article discovery, translations, runtime tag replacement, responsive rendering, derivative caching, source invalidation, and signed-route security.

License

Blogframe is open-source software licensed under the MIT license.