Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
35 commits
Select commit Hold shift + click to select a range
acb56a5
Add AppVersion class as single source of the version
Neluxx Oct 28, 2026
9a5c0be
Add AppVersion view helper with meta tag
Neluxx Oct 28, 2026
80ca634
Add JSON version endpoint controller
Neluxx Oct 28, 2026
69438fa
Fix CS
Neluxx Oct 28, 2026
5732eca
Add app_version CLI command
Neluxx Oct 28, 2026
b86f182
Add optional CLI version banner
Neluxx Oct 28, 2026
b57699d
Register version endpoint, CLI command and banner in plugin
Neluxx Oct 28, 2026
64d6d60
Document new app version outputs
Neluxx Oct 28, 2026
608a83a
Remove CLI banner listener
Neluxx Oct 29, 2026
488b61a
Rename AppVersionController to VersionController
Neluxx Oct 29, 2026
3a85571
Simplify $version check
Neluxx Nov 2, 2026
6c8182b
Improve usage documentation
Neluxx Nov 2, 2026
2ab4d91
Change path from /version to /app-version
Neluxx Nov 2, 2026
e3f6829
Merge remote-tracking branch 'origin/18-add-more-ways-to-expose-app-v…
Neluxx Nov 2, 2026
b2632dc
Adjust tests
Neluxx Nov 2, 2026
5668bd1
Rename version to app-version in JSON response
Neluxx Nov 5, 2026
9f508a7
Remove meta.enabled config
Neluxx Nov 5, 2026
bbfa621
Update docs/Configuration.md
Neluxx Nov 5, 2026
9760ba4
Update docs/Configuration.md
Neluxx Nov 5, 2026
4392c2d
Merge remote-tracking branch 'origin/18-add-more-ways-to-expose-app-v…
Neluxx Nov 5, 2026
6a6d639
Serve app version endpoint as JSON or HTML depending on extension
Neluxx Nov 6, 2026
8465085
Leave version endpoint routing to the application
Neluxx Nov 6, 2026
de0976d
Add getUrlEncoded() to AppVersion helper
Neluxx Nov 6, 2026
f415956
Update usage docs and changelog
Neluxx Nov 6, 2026
976f96f
Remove plugin configuration
Neluxx Nov 6, 2026
af712e7
Improve documentation
Neluxx Nov 18, 2026
60d0e31
Use the proper coverage annotation
Neluxx Nov 18, 2026
9d74ea9
Fetch the request and view builder once
Neluxx Nov 18, 2026
623e28b
Add AppVersion::extractVersion() to read the version file
Neluxx Nov 18, 2026
9198718
Rename the version endpoint action from index to show
Neluxx Nov 18, 2026
5be5d98
Serve the app version endpoint as XML as well
Neluxx Nov 18, 2026
ca88463
Update change log
Neluxx Nov 18, 2026
59af022
Move the security considerations to the usage guide
Neluxx Nov 18, 2026
ed4bf89
Update the installation guide for CakePHP 5 and link the guides
Neluxx Nov 18, 2026
f9971b3
Improve usage documentation
Neluxx Nov 18, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,11 @@ This project adheres to [Semantic Versioning](http://semver.org/).
## [Unreleased](https://github.com/orca-services/cakephp-app-version)

### Added
- More ways to expose the app version, all reading `App.version` [#18](https://github.com/orca-services/cakephp-app-version/issues/18):
- `AppVersion` view helper with `get()`, `getUrlEncoded()` and `meta()`
- Version endpoint controller serving JSON, XML or HTML depending on the extension, e.g. `GET /app-version.json`
- `bin/cake app_version` CLI command
- `AppVersion::extractVersion()` to read the app version from a `VERSION` file

### Changed

Expand Down
6 changes: 4 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,17 @@
# CakePHP App Version Plugin

A CakePHP plugin for adding a configurable app version as an HTTP header.
A CakePHP plugin for exposing a configurable app version as an HTTP header, in views (helper, meta tag), via an
endpoint (as JSON, XML or HTML) and on the CLI.

## Compatibility

| Plugin Version | CakePHP Compatibility | Branch | Status |
|----------------|-----------------------|-------------| --------- |
|----------------|-----------------------|-------------|-----------|
| 1.x | 5.x | cakephp-5.x | Supported |
| 0.x | 4.x | cakephp-4.x | Supported |

Note:

- There is no plugin version for CakePHP 3.x.
- Previous versions of the plugin that supported previous versions of CakePHP are not supported anymore.

Expand Down
12 changes: 10 additions & 2 deletions composer.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,15 @@
{
"name": "orca-services/cakephp-app-version",
"description": "A CakePHP plugin for adding a configurable app version as an HTTP header",
"keywords": ["CakePHP", "Plugin", "HTTP", "Headers", "Application version"],
"description": "A CakePHP plugin for exposing a configurable app version as an HTTP header, in views, via an endpoint and on the CLI",
"keywords": [
"CakePHP",
"Plugin",
"HTTP",
"Headers",
"Application version",
"View helper",
"CLI"
],
"type": "cakephp-plugin",
"homepage": "https://github.com/orca-services/cakephp-app-version",
"license": "MIT",
Expand Down
28 changes: 18 additions & 10 deletions docs/Configuration.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,16 @@
# Configuration

The plugin reads two values from CakePHP's `Configure` registry:
## App version

| Key | Purpose | Default |
All outputs of the plugin read the version from CakePHP's `Configure` registry.
`App.version` is the **single source of truth**:

| Key | Purpose | Fallback |
|---------------------|---------------------------------------|-------------|
| `App.version` | The version string to expose | `"Unknown"` |
| `App.versionPrefix` | The vendor prefix for the header name | `"X"` |

Set them in `config/app.php` (or `config/app_local.php`):
Set them in `config/app.php` (or `config/app_local.php`), like so:

```php
'App' => [
Expand All @@ -16,23 +19,28 @@ Set them in `config/app.php` (or `config/app_local.php`):
],
```

This will produce the HTTP response header:
With the [header middleware](Usage.md#http-response-header) this will add a HTTP response header:

```
Acme-App-Version: 1.2.3
```

To keep the version in sync with your release process, read it dynamically in `config/bootstrap.php`, for example from a `VERSION` file:
To keep the version in sync with your release process, read it dynamically in `config/bootstrap.php`
from a version file:

```php
Configure::write(
'App.version',
trim((string)@file_get_contents(ROOT . DS . 'VERSION')) ?: 'Unknown'
);
use AppVersion\AppVersion;

Configure::write('App.version', AppVersion::extractVersion());
```

By default, `AppVersion::extractVersion()` reads the `VERSION` file in your application's root directory
(`AppVersion::DEFAULT_VERSION_FILE`) and removes leading and trailing whitespace.
Pass another path to read a different file, e.g. `AppVersion::extractVersion(CONFIG . 'version.txt')`.
If the file is missing, unreadable or empty, `"Unknown"` is returned.

Make sure this runs before the middleware queue is built.

---

Back to the [Documentation](../README.md).
Continue with the [usage](./Usage.md) or Back to the [documentation](../README.md).
18 changes: 12 additions & 6 deletions docs/Installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

### Requirements

- PHP >= 7.4
- CakePHP 4.x
- PHP >= 8.2
- CakePHP >= 5.3.6

### CakePHP Version Support

Expand All @@ -17,15 +17,21 @@ First, require the package through Composer:
composer require orca-services/cakephp-app-version
````

Then load the plugin in your application as documented in the section
[Loading a Plugin](https://book.cakephp.org/4.x/plugins.html#loading-a-plugin)
Then load the plugin in your application with the plugin load command:

````
php bin/cake.php plugin load AppVersion
````

Alternatively, load it manually as documented in the section
[Loading a Plugin](https://book.cakephp.org/5.x/plugins.html#loading-a-plugin)
in the CakePHP CookBook.

### Installation alternatives

Refer to the CakePHP CookBook section
[Manually Installing a Plugin](https://book.cakephp.org/4.x/plugins.html#manually-installing-a-plugin).
[Manually Installing a Plugin](https://book.cakephp.org/5.x/plugins.html#manually-installing-a-plugin).

---

Back to the [Documentation](../README.md).
Continue with the [configuration](./Configuration.md) or Back to the [documentation](../README.md).
157 changes: 154 additions & 3 deletions docs/Usage.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,21 @@
# Usage

Once the plugin is installed and loaded (see [Installation](Installation.md)), add the middleware to your middleware queue in `src/Application.php`:
Once the plugin is [installed and loaded](Installation.md), the app version can be exposed in several ways.

All of them read the same `App.version` value from the [configuration](Configuration.md).
If `App.version` is not set, all of them return `"Unknown"` instead.

| Output | Example | Available |
|-----------------------------------------------|-----------------------------------------------------|-------------------------------------|
| [HTTP response header](#http-response-header) | `X-App-Version: 1.2.3` | When the middleware is added |
| [View helper](#view-helper) | `$this->AppVersion->get()` → `1.2.3` | When the helper is loaded |
| [HTML meta tag](#html-meta-tag) | `<meta name="app-version" content="1.2.3">` | When `meta()` is used in a template |
| [Version endpoint](#version-endpoint) | `GET /app-version.json` → `{"app-version":"1.2.3"}` | When you connect its route |
| [CLI command](#cli-command) | `bin/cake app_version` → `1.2.3` | Always |

## HTTP response header

Add the app version [middleware](https://book.cakephp.org/5.x/controllers/middleware.html#middleware) to your [middleware queue](https://book.cakephp.org/5.x/controllers/middleware.html#using-middleware) in `src/Application.php`:

```php
use AppVersion\Middleware\AppVersionHeaderMiddleware;
Expand All @@ -18,14 +33,150 @@ public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue

Add `AppVersionHeaderMiddleware` **before** `ErrorHandlerMiddleware` if you want the header to be present on error responses as well.

Configure the header value and prefix as described in [Configuration](Configuration.md).

Every response will then include an HTTP header of the form:

```
{Prefix}-App-Version: {Version}
```

## View helper

Load the [helper](https://book.cakephp.org/5.x/views/helpers.html#helpers) in your view class, e.g. `src/View/AppView.php`,
and type hint it in the class docblock for IDE autocompletion and static analysis:

```php
/**
* @property \AppVersion\View\Helper\AppVersionHelper $AppVersion
*/
class AppView extends View
{
public function initialize(): void
{
parent::initialize();

$this->addHelper('AppVersion.AppVersion');
}
}
```

Then use it in your templates, e.g. in a footer:

```php
<footer>Version <?= h($this->AppVersion->get()) ?></footer>

<?= $this->Html->script('app.js?v=' . $this->AppVersion->getUrlEncoded()) ?>
```

`get()` returns the raw version, escape it with [`h()`](https://book.cakephp.org/5.x/core-libraries/global-constants-and-functions.html#h) when printing it in HTML.
`getUrlEncoded()` returns the URL encoded version, e.g. for cache busting query strings.

## HTML meta tag

Add an app version [meta tag](https://book.cakephp.org/5.x/views/helpers/html.html#creating-meta-tags) to your [layout](https://book.cakephp.org/5.x/views.html#layouts), e.g. `templates/layout/default.php`:

```php
<head>
<?= $this->AppVersion->meta() ?>
</head>
```

This renders:

```html
<head>
<meta name="app-version" content="1.2.3">
</head>
```

To append it to the `meta` view block instead, pass `['block' => true]`.

The version can then be read from frontend code or E2E tests:

```js
document.querySelector('meta[name="app-version"]')?.content;
```

## Version endpoint

The plugin does not connect any route on its own, so the version endpoint is only available if you connect it
in your [routes](https://book.cakephp.org/5.x/development/routing.html#quick-tour), e.g. in `config/routes.php`:

```php
$routes->scope('/', function (RouteBuilder $builder): void {
$builder->get(
'/app-version',
['plugin' => 'AppVersion', 'controller' => 'Version', 'action' => 'show'],
'AppVersion.version',
)->setExtensions(['json', 'xml', 'html']);
});
```

You are free to choose the connected URL path and route name. You decide in which environments the route is connected.

The response format depends on the [file extension](https://book.cakephp.org/5.x/development/routing.html#routing-file-extensions):

```
$ curl https://example.com/app-version.json
{"app-version":"1.2.3"}

$ curl https://example.com/app-version.xml
<?xml version="1.0" encoding="UTF-8"?>
<response><app-version>1.2.3</app-version></response>

$ curl https://example.com/app-version.html
$ curl https://example.com/app-version
<!DOCTYPE html> [...] App version: <span class="app-version">1.2.3</span> [...]
```

Without an extension, HTML is returned. The HTML template can be overridden in your application with
`templates/plugin/AppVersion/Version/show.php`.

This lets deploy pipelines, smoke tests, uptime monitors and load balancers verify which release is live.
The response is sent with `Cache-Control: no-store`.

### Security considerations

Exposing the exact version publicly can help attackers to fingerprint your app.
That is why the plugin never connects the version endpoint on its own.
Connect its route only where you need it, e.g. only on staging, and restrict access if necessary.

For the same reason, the endpoint deliberately only returns the app version, but not the PHP or CakePHP version.
Those would tell attackers exactly which known vulnerabilities of the platform to try,
while they are of no use to deploy pipelines or monitors.
If you need them, use the [CLI command](#cli-command) on the server.

To restrict access, [apply route middleware](https://book.cakephp.org/5.x/development/routing.html#route-scoped-middleware) the same way as for any other route of your application:

```php
$routes->scope('/', function (RouteBuilder $builder): void {
$builder->registerMiddleware('versionAuth', new MyIpAllowListMiddleware());

$builder->get(
'/app-version',
['plugin' => 'AppVersion', 'controller' => 'Version', 'action' => 'show'],
'AppVersion.version',
)
->setExtensions(['json', 'xml', 'html'])
->setMiddleware(['versionAuth']);
});
```

## CLI command

Print the version on the server or in deploy scripts without HTTP access:
Comment thread
Neluxx marked this conversation as resolved.
Resolved

```
$ bin/cake app_version
1.2.3
```

Use the `--full` (or `-f`) option to also print the PHP version, the CakePHP version and the debug mode:

```
$ bin/cake app_version --full
PHP 8.3.6, CakePHP 5.3.6 (debug: false), app version 1.2.3
```

---

Back to the [Documentation](../README.md).
66 changes: 66 additions & 0 deletions src/AppVersion.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
<?php
declare(strict_types=1);

namespace AppVersion;

use Cake\Core\Configure;

/**
* App Version
*
* Central access point for the app version.
*/
class AppVersion
{
/**
* The version string to be returned if `App.version` is not set.
*
* @var string
*/
public const UNKNOWN = 'Unknown';

/**
* The default path of the file containing the app version.
*
* @var string
*/
public const DEFAULT_VERSION_FILE = ROOT . DS . 'VERSION';

/**
* Get the configured app version.
*
* @return string The app version or "Unknown" if it is not set.
*/
public static function get(): string
{
$version = Configure::read('App.version');

if (!$version || !is_scalar($version)) {
return self::UNKNOWN;
}

return (string)$version;
}

/**
* Extract the app version from a version file, e.g. to set `App.version` in `config/bootstrap.php`.
*
* Leading and trailing whitespace is removed.
*
* @param string $versionFilePath The path of the file containing the app version.
* @return string The app version or "Unknown" if the file is missing, unreadable or empty.
*/
public static function extractVersion(string $versionFilePath = self::DEFAULT_VERSION_FILE): string
{
if (!is_file($versionFilePath) || !is_readable($versionFilePath)) {
return self::UNKNOWN;
}

$version = trim((string)file_get_contents($versionFilePath));
if ($version === '') {
return self::UNKNOWN;
}

return $version;
}
}
Loading
Loading