otaqq / form-datalayer
Measure every form step (input, confirm, complete, error) with Google Tag Manager: a catalog in your code, settings chosen on an admin screen, and nothing sent unless allowed.
Requires
- php: ^8.3
- ext-json: *
- ext-mbstring: *
- psr/log: ^2.0|^3.0
Requires (Dev)
- illuminate/database: ^12.0|^13.0
- illuminate/support: ^12.0|^13.0
- orchestra/testbench: ^10.0|^11.0
- phpunit/phpunit: ^11.5|^12.5
Suggests
- illuminate/support: For the Laravel integration (^12.0|^13.0): config, steps from route names, Blade, the settings screen and a check command
Provides
None
Conflicts
None
Replaces
None
README
Measure every form step — input, confirm, complete, error — with Google Tag Manager, from routes and a catalog in your code, and settings changed on an admin screen.
Tag managers are easy to add and hard to keep honest. Events get hand-written in templates, forms added later are forgotten, and sooner or later a name or an email address ends up in dataLayer. form-datalayer turns that around:
- A catalog in git. The app lists its forms and pages, the steps of each, and the only values each may send. Reviewed like code; checked against a JSON Schema.
- Pages from routes. Mark a route with its form and step; added and removed routes show up on the settings screen by themselves. Event names are made from the key (
front.entry→front_entry_confirm). - Nothing sent unless allowed. No request input reaches the page unless the catalog lists it. Ids can be turned into names (
prefecture_id→Tokyo). - Settings without a deploy. The GTM container ids, which forms are on, event names, and which parameters each step sends are chosen on an admin screen — checkboxes from the catalog, no free scripts — and saved to a JSON file outside the repository.
- Safe to change over time. Parameters removed from the catalog stop being sent; new ones wait to be chosen; stale settings never break a page.
- One spec, many languages. The rules live in spec/ and are checked by shared data in conformance/. PHP (with Laravel) comes first.
Status: v0.1: PHP and Laravel, in use in one application. Other languages are planned; see docs/roadmap.md.
Layout
| Path | What | Package |
|---|---|---|
| spec | What every implementation does, and the JSON Schemas | — |
| conformance | Shared inputs and expected results | — |
lang/php/core |
Framework-independent PHP: catalog, settings, pushes, output | Composer otaqq/form-datalayer |
lang/php/laravel |
Laravel: config, steps from route names, flash, Blade, settings screen, check command | Composer otaqq/form-datalayer |
Laravel
composer require otaqq/form-datalayer php artisan vendor:publish --tag=form-datalayer-config
Mark the pages of each form on its routes. Adding or removing a route adds or removes the page; nothing else to keep in sync:
Route::get('entry/{posting}', [EntryController::class, 'create'])->name('entries.create')->dataLayer('front.entry', 'input'); Route::post('entry/{posting}/confirm', [EntryController::class, 'confirm'])->dataLayer('front.entry', 'confirm'); Route::get('entry/{posting}/complete', [EntryController::class, 'complete'])->dataLayer('front.entry', 'complete'); Route::get('prefectures/create', …)->dataLayer('admin.prefecture', 'input', mode: 'create'); Route::get('prefectures/{id}/edit', …)->dataLayer('admin.prefecture', 'input', mode: 'edit'); Route::post('prefectures/confirm', …)->dataLayer('admin.prefecture', 'complete'); // redirects to the list
- An
inputpage that comes back with validation errors pusheserror. - A
completeroute that redirects pushescompleteon the next page, unless it flashed validation errors or one of the flash keys infailures('failures' => ['error']). Set its mode withFormDatalayer::mode('edit').
Write the labels and the values each form may send in form-datalayer.json at the root of the app (spec/catalog.md). Only these values can ever reach the page:
{
"version": 1,
"forms": {
"front.entry": {
"label": "Job application",
"params": {
"posting_code": {"label": "Posting code", "from": "posting.code", "default": true},
"prefectures": {"label": "Prefectures", "from": "posting.prefecture_ids.*",
"lookup": {"table": "prefectures", "key": "id", "column": "name"}}
}
}
}
}
Give the values from controllers:
use Otaqq\FormDatalayer\Laravel\Facades\FormDatalayer; FormDatalayer::with(['posting' => $posting]); // values for this request's pushes
Declare the containers and the tab labels in config/form-datalayer.php. The GTM id is entered on the settings screen; a container that follows another is a checkbox there (one GTM container, chosen per area):
'containers' => [ 'front' => ['label' => 'Public site', 'default' => ''], 'admin' => ['label' => 'Admin screen', 'follows' => 'front'], ], 'groups' => ['front' => 'Public site', 'admin' => 'Admin screen'],
Put the tag in each layout, naming its container:
<head> @formDatalayerHead('front') </head> <body> @formDatalayerBody('front')
The settings screen is at /form-datalayer for users with the form-datalayer.manage ability, which the app defines. It lists the forms in one tab per group (the first word of the key); each form has a page for its event names and values. Forms are off until checked there; new forms are marked as new.
Gate::define('form-datalayer.manage', fn ($user) => in_array($user->role, ['system_admin', 'service_admin'], true));
The settings are saved to storage/app/private/form-datalayer.json (FORM_DATALAYER_SETTINGS): keep it on storage that survives deploys. Publish the views (--tag=form-datalayer-views: index and form) to put the screen in your layout. After a deploy, php artisan form-datalayer:check lists new forms and parameters, and settings that name what is gone.
Upgrading from v0.2
- Forms are off until turned on. Forms the saved settings do not turn on (
"enabled": true) stop pushing. Check them on the list and save. - Pages that are not forms (
view) are gone: drop them from the catalog. Their saved settings are listed as removed and dropped on the next save. - Move
stepsfrom the catalog to the routes (->dataLayer()); a page may not be in both. Calls toFormDatalayer::flash(…, 'complete', …)can become->dataLayer(…, 'complete')on the route that redirects. - The settings view is now two views,
indexandform: publish them again if you had publishedsettings.
License
MIT