Task: Investigate Composer / Packagist / PSR-4 Modules in Trongate v2

[trongate]

Task: Investigate Composer / Packagist / PSR-4 Modules in Trongate v2

I would like to create a page of documentation for the Trongate framework explaining how developers can create Trongate modules that work with Composer, Packagist and PSR-4 autoloading.

This work will be carried out in two phases.

Phase 1 - Investigation

Grady is responsible for this phase.

Your job is to investigate the subject thoroughly and get a very basic working example running against the latest version of Trongate v2.

Do not attempt to write the final polished documentation. Instead, document your findings clearly so that another agent can use your notes to produce the final documentation later.

Useful reference

There is an existing YouTube video covering this subject:

https://www.youtube.com/watch?v=oVSDrG4ibrI

However, this video was produced for Trongate v1.

Please watch/review it where possible and determine which parts of the process remain applicable to Trongate v2 and which parts need to be changed.

Do not assume that the v1 process is still correct. Verify everything against the current v2 framework.

What needs to be investigated

Determine how a developer can create a basic Trongate v2 module that:

1. Exists within a normal Trongate v2 application.
2. Uses Composer for dependency management.
3. Can use a third-party package installed through Composer.
4. Uses PSR-4 autoloading where appropriate.
5. Can potentially be distributed through Packagist.
6. Can be loaded and used correctly by a Trongate module.
7. Works correctly with the current Trongate v2 directory structure and bootstrap process.

Investigate the relationship between the Trongate framework's own autoloading mechanism and Composer's autoloader.

In particular, establish exactly where and how Composer's autoloader needs to be loaded, if it needs to be loaded explicitly at all.

use statements

Pay particular attention to the possibility of using PHP use statements within Trongate classes.

For example:

<?php
use Aws\CloudFront\CloudFrontClient;

class Training extends Trongate {

Determine whether this approach works correctly in Trongate v2 and, if so, document the exact circumstances and requirements.

Do not assume that simply adding a use statement is sufficient. Verify the complete process, including Composer installation, autoloading and framework execution.

Starter example

Create the simplest possible working example that demonstrates the concept.

The example should preferably use a real Composer package rather than a completely artificial package.

The objective is not to build a sophisticated module. We want a minimal proof of concept that demonstrates:

Trongate v2 module → Composer → PSR-4 autoloading → third-party PHP class/package → successful execution.

Record the exact steps required to reproduce the example.

Where appropriate, record:

• Directory structure.
• composer.json contents.
• Composer commands used.
• Namespace declarations.
• use statements.
• Any changes required within the Trongate application.
• Any changes required within the module.
• How the module was accessed/tested.
• Expected output.
• Any errors encountered and how they were resolved.

Packagist investigation

Also investigate what would be required for a Trongate module to become a Composer package that could be published to Packagist.

Establish the distinction between:

• A Trongate module using a Composer package.
• A Trongate module being distributed as a Composer package.
• A package being registered on Packagist.

Do not over-engineer this phase. The immediate objective is to understand the basic mechanism and establish a reliable starter example.

Important: use the current framework

Use the latest Trongate v2 codebase for all testing.

Do not make assumptions based solely on Trongate v1.

If the v1 YouTube video demonstrates a technique that no longer applies, explicitly record that.

Likewise, if the v1 technique still works in v2, record that and explain why.

Record your findings

Create a clear investigation report/page containing all findings.

The report should include:

• What works
• What does not work
• What has changed from v1
• The working starter example
• Required directory structure
• Required Composer configuration
• Required PHP namespaces / use statements
• How Composer's autoloader interacts with Trongate
• How a module could potentially be packaged for Packagist
• Any limitations, caveats or unresolved questions

Include the actual code used to prove the concept.

The report does not need to be beautifully written. Accuracy and reproducibility are more important at this stage.

Phase 1 deliverable

The final deliverable from Grady should be a technical investigation report, not the finished public-facing documentation.

Once this investigation is complete, I will ask Mike to use Grady's findings to write the actual Trongate framework documentation page.

Do not make unnecessary changes to the Trongate framework itself.

The goal of this phase is to understand the process, prove it works with Trongate v2, and leave Mike with enough accurate information to produce the final documentation.

[grady-trongate]

Reference material only — for the writing brief, suggested title and page structure, see the final comment in this thread.

---

Trongate v2 + Composer: Technical Investigation Report

Task: #96
Author: Grady (investigation only — this is not the finished public documentation page)
Date: 21 September 2026
Status: Investigation complete. All claims below were verified by running code against a live Trongate v2 installation.

---

0. Executive summary

#	Question asked by the issue	Verdict
1	Does a Trongate v2 module work with third-party packages installed via Composer?	Yes. Verified end-to-end over HTTP and CLI.
2	Can use statements be used inside Trongate classes (e.g. class Training extends Trongate)?	Yes — in controllers, models and views.
3	What is the relationship between Trongate's own autoloader and Composer's?	They are independent and complementary. Trongate never looks inside vendor/; Composer never looks inside modules/. Composer's loader is registered first, so Composer-resolvable classes always win. Details in §1.
4	Where must Composer's autoloader be loaded?	It must be loaded explicitly — the framework does not load it for you. Three valid places; the recommended one is public/index.php. Details in §2.
5	Can a Trongate module itself be distributed as a Composer/Packagist package?	Yes, and it works well, but it needs one extra piece: a small installer plugin (or a self-written type + installer) so that the module lands in modules/ rather than vendor/. Details in §9.
6	Does the v1 video (oVSDrG4ibrI) still apply to v2?	Both halves still apply, with caveats. Details in §4.

Deliverables/artefacts produced during this investigation:

• Working proof-of-concept app: /var/www/html/composer_poc (a pristine clone of trongate/trongate-framework master, commit 6b0d0f7, version 2.2026.0920d).
• Local Composer package repository: /var/www/html/pkg-repo/ (4 packages) and a git-tagged repo at /var/www/html/vcs-repo/vat-tools.
• Reproduction commands: Appendix C.

---

1. How Trongate v2 loads classes (its own autoloader)

engine/ignition.php registers one SPL autoloader and nothing else:

spl_autoload_register(function ($class_name) {
    // 1) engine directory (e.g. Core, Model, Trongate)
    // 2) modules/{lowercase_class_name}/{Class}.php
});

Consequences that matter for this investigation:

• F1. Trongate's loader has no knowledge of vendor/. A grep of the whole engine/ directory returns zero references to vendor/autoload.php or any autoload bootstrap. The only vendor awareness in core is the static-asset route described in §5 (Core::serve_vendor_asset()), which is about serving files over HTTP, not about PHP class loading.

• F2. Class names are matched as-is: modules/ + strtolower($class_name) + / + $class_name + .php. Namespaced names (Foo\Bar) therefore cannot be resolved by Trongate's loader — which is exactly why Composer's PSR-4 loader is needed, and why the two autoloaders do not fight (see F4).

• F3. Controller, model and view files are require/require_onced explicitly by the framework (Modules::run() loads APPPATH . 'modules/{module}/{Controller}.php'; Model::load_model() loads ../modules/{module}/{Module}_model.php). Because these files are included normally, a plain PHP use statement at the top of them behaves exactly as it does in any PHP file.

• F4. Because public/index.php requires vendor/autoload.php after ignition.php, and Composer's ClassLoader::register() prepends itself to the autoloader stack, the runtime order is:

  autoloader 0: Composer\Autoload\ClassLoader
  autoloader 1: Closure            ← Trongate's own loader
  

  (Captured live from http://localhost/composer_poc/composer_demo/check.)
  Namespaced third-party classes are therefore always resolved by Composer; framework classes continue to be resolved by Trongate's closure. Note the corollary: a package that declares a global (non-namespaced) class whose name collides with a framework class will shadow it. Verified deliberately — see §11, S1.

---

2. Where to load Composer's autoloader (the core question)

It must be loaded explicitly. An unloaded autoloader produces a hard, silent-to-the-user failure:

• HTTP: 500 with a zero-length body (no error text shown).
• CLI / error log: PHP Fatal error: Uncaught Error: Class "GradyPoc\InvoiceKit\Invoice_kit" not found in .../modules/composer_demo/Composer_demo.php:77 (and, for Dompdf, Uncaught ReflectionException: Class "Carbon\Carbon" does not exist).

Three placements were tested. All three work; they are appropriate for different situations.

Option A — public/index.php (recommended default)

<?php
require_once '../engine/ignition.php';

// Composer's autoloader. APPPATH points at the application root.
require_once APPPATH . 'vendor/autoload.php';

//Init Core Library
$init = new Core;

• Matches the v1 video, and matches the snippet already published in 0050Module_Fundamentals/0003controller_files.html (require_once APPPATH.'vendor/autoload.php'; + use GuzzleHttp\Client;).
• One line, loaded once per request, available to every module.
• Uses APPPATH, which ignition.php has already defined by that point. require_once __DIR__ . '/../vendor/autoload.php'; is an equally valid, CWD-independent alternative.
• Downside: it edits a framework file. Anyone who upgrades by copying a fresh public/index.php loses the line (silently).

Option B — top of a module controller file (best for distributable modules)

<?php
require_once APPPATH . 'vendor/autoload.php';

use Dompdf\Dompdf;
use Carbon\Carbon;

class Composer_self extends Trongate { ... }

• Verified working (module composer_self, http://localhost/composer_poc/composer_self/ → 200).
• Legal PHP: use statements may follow a require_once; they are compile-time aliases for the rest of the file.
• Keeps a reusable module self-sufficient: drop the module into any Trongate v2 app and it works, with a pristine core. This is the form I would recommend for modules that are intended to be shared (including module-as-Composer-package, §9).
• Downside: repeated require_once per module file (harmless — require_once is idempotent) and it requires APPPATH to be defined, which is true for anything loaded by the framework.

Option C — CLI / cron entry point (mandatory for non-web context)

The web entry point does not cover scripts run from a shell. A CLI script must bootstrap the framework and the autoloader itself:

<?php
$_SERVER['REQUEST_METHOD'] = $_SERVER['REQUEST_METHOD'] ?? 'GET';
$_SERVER['HTTP_HOST']      = $_SERVER['HTTP_HOST']      ?? 'localhost';
$_SERVER['REQUEST_URI']    = $_SERVER['REQUEST_URI']    ?? '/';

chdir(__DIR__ . '/../public');          // see F5
require_once '../engine/ignition.php';
require_once APPPATH . 'vendor/autoload.php';

Modules::run('composer_demo/kit');

• F5 (gotcha). Trongate's bootstrap uses path-relative requires (ignition.php does require_once '../config/config.php'; Core/Model use ../modules/...). A CLI entry point that does not chdir() into public/ dies with Failed opening required '../config/config.php'. This is a pre-existing framework characteristic, not a Composer issue, but it bites immediately when you try to use a package from a script.
• Also needs the $_SERVER pseudo-variables above, otherwise Undefined array key "REQUEST_METHOD"/"HTTP_HOST"/"REQUEST_URI" warnings appear.
• Verified output: Invoice_kit class file: /var/www/html/pkg-repo/invoice-kit/src/Invoice_kit.php, plus a clean exit.

Not viable: putting the require in config/config.php or in a view. Config is included by ignition.php before APPPATH-dependent logic is reliable and is a poor place for a cross-cutting include; views are far too late (the controller has already used the class by then).

---

3. use statements inside Trongate classes — verified

Location	Test	Result
Controller (Composer_demo extends Trongate)	use Dompdf\Dompdf; use Carbon\Carbon; use GradyPoc\InvoiceKit\Invoice_kit; then instantiate	✅ 200, classes resolve
Controller (same file, own PSR-4 class)	use Trongate\ComposerDemo\Invoice_builder; mapped to modules/composer_demo/src/ by the app's own composer.json	✅ works
Model (Composer_demo_model extends Model)	use GradyPoc\VatTools\Vat_tools; in a method delegated to via $this->model->net_from_gross(240.00)	✅ returned 200
View (views/model_check.php)	use Carbon\Carbon; at the top of the view, then Carbon::parse('2026-01-31')->addMonth()	✅ returned 2026-03-03

Conclusion: PHP namespaces / use are entirely compatible with Trongate v2's coding standards. The only Prologate-specific rule that remains is that the class declared in a Trongate module file must stay global (e.g. class Training extends Trongate), because the framework resolves it via its own loader by file name.

---

4. The v1 video (https://www.youtube.com/watch?v=oVSDrG4ibrI) — what still applies

Part 1 — Dompdf (≈00:00–03:00). Still 100% applicable. The steps in the video are exactly the steps that work in v2:

1. composer require dompdf/dompdf
2. require_once '../vendor/autoload.php'; in public/index.php (= Option A above)
3. use Dompdf\Dompdf; at the top of the module file
4. Instantiate and render.

Verified with Dompdf 3.1.6 in v2 at http://localhost/composer_poc/composer_demo/pdf (returns a real application/pdf).

Part 2 — "how do I reference JS/CSS-heavy packages like TinyMCE?" (≈03:00–07:30). Still applicable in v2, and the framework now has a dedicated mechanism. The video's finding was that a package containing no PHP at all (TinyMCE: CSS, themes, skins, plugins, no PHP files) is unusable unless the framework can serve those files from vendor/. The video's solution — reference the path /vendor/... in the URL and let the framework serve the file — is a first-class feature in v2: Core::serve_vendor_asset(), which triggers whenever the request URL contains /vendor/. Verified live in v2:

Request	Result
/composer_poc/vendor/dompdf/dompdf/lib/res/html.css	200, Content-Type: text/css
/composer_poc/vendor/poc-asset/demo.js (temp file)	200, Content-Type: text/plain ⚠️
/composer_poc/vendor/composer/InstalledVersions.php	200, Content-Type: text/plain — PHP source served verbatim ⚠️
/composer_poc/vendor/../config/config.php (and %2e%2e, %252e%252e, //etc/passwd)	404, Invalid file path or directory traversal detected. ✅

Caveats worth putting in the documentation (see §11):

• Only paths containing .css are given a CSS content type; everything else is served as text/plain, including .js, fonts, images and .php. Classic <script src> tags still execute in most browsers, but ES modules and strict-nosniff setups will refuse a text/plain script — a trivial future improvement would be a proper MIME map for .js, .mjs, .woff2, .svg, .map, etc. (framework change — not made, per instruction).
• Because .php files are echoed as text, nothing secret should ever live under vendor/.

One thing the video does not cover, and the docs should: how to consume a package through Composer when the app is deployed without a shell (see §9) and the fact that vendor/ should be git-ignored.

---

5. Complete working example (the "basic working example" the issue asks for)

Minimal, self-contained recipe, exactly as verified.

5.1 Install

cd /path/to/trongate-app
composer require dompdf/dompdf      # or: composer require nesbot/carbon

5.2 Load Composer's autoloader

// public/index.php  (Option A)
require_once '../engine/ignition.php';
require_once APPPATH . 'vendor/autoload.php';
$init = new Core;

5.3 Use it in a module

modules/invoices/Invoices.php

<?php
use Dompdf\Dompdf;
use Carbon\Carbon;

class Invoices extends Trongate {

    public function test(): void {
        $dompdf = new Dompdf();
        $dompdf->loadHtml('<h1>Hello from Trongate v2</h1><p>' . Carbon::now()->toDateTimeString() . '</p>');
        $dompdf->render();

        header('Content-Type: application/pdf');
        echo $dompdf->output();
    }

}

Visit /invoices/test → PDF rendered by a Composer-installed package. That is the whole recipe. (This is the video's workflow, unchanged, re-verified on v2.)

5.4 A module that carries its own PSR-4 classes

Add to the app's composer.json:

"autoload": {
    "psr-4": {
        "Trongate\\ComposerDemo\\": "modules/composer_demo/src/"
    }
}

then composer dump-autoload. Verified: modules/composer_demo/src/Invoice_builder.php (namespace Trongate\ComposerDemo;) loads and is used from the controller by use Trongate\ComposerDemo\Invoice_builder;. Note this does require editing the app's composer.json — the alternative (Option B, require_once APPPATH.'vendor/autoload.php' + a package published on a repository) is the one that keeps the app's own composer.json untouched.

---

6. Test matrix (all executed, all green at time of writing)

App: http://localhost/composer_poc/ (DocumentRoot /var/www/html, Apache 2.4.66 + mod_php 8.4.16, PHP 8.4.16, Composer 2.10.3).

#	Test	Command / URL	Result
T1	framework boots	/composer_poc/	200
T2	Composer autoloader present in v2	/composer_demo/check	composer_class_loader: true, autoloader order = Composer, Closure
T3	third-party PSR-4 class	/composer_demo/dates	Carbon resolves, addDays(7), diffForHumans() OK
T4	PSR-4 transitive dep (symfony/clock, psr/clock, carbon-doctrine-types)	same request	all autoloaded
T5	PDF generation	/composer_demo/pdf	valid PDF bytes
T6	module's own PSR-4 namespace	/composer_demo/psr4	class file = modules/composer_demo/src/Invoice_builder.php
T7	external package (path repo)	/composer_demo/kit	net: 82.5 / vat: 16.5 / gross: 99
T8	external package (git/VCS repo, tagged v1.0.0)	/composer_demo/vat	reverse VAT 120.00 → 100
T9	autoloader required inside the module file (Option B)	/composer_self/	Dompdf + Carbon resolve
T10	use in model file	/composer_demo/model_check	240.00 gross → 200 net
T11	use in view file	same page	2026-03-03
T12	module distributed as a Composer package	/invoices/	200, controller file inside modules/invoices/
T13	second module package, different name	/reports/	200
T14	CLI entry point	php cli/with_chdir.php	kit summary printed, clean exit
T15	use of a namespace with no autoloader	(autoloader removed)	HTTP 500 / CLI Class "..." not found — reproduces the failure mode
T16	clean-room reproducibility	rm -rf vendor modules/invoices modules/reports && composer install	all 12 routes back to 200
T17	/vendor/ asset route	…/vendor/dompdf/dompdf/lib/res/html.css	200 text/css
T18	traversal guard	4 encoded variants	all 404 Invalid file path or directory traversal detected.

---

7. Errors encountered (and how each was resolved)

#	Symptom	Cause	Resolution
E1	HTTP 500, empty response body; nothing in the browser	Class not found because the autoloader was never required. ENV=dev still produced no visible error	Diagnose via CLI harness (php -r with display_errors=1) or the Apache error log. Lesson for docs: "500 with empty body" is the signature of a missing Composer autoloader
E2	Uncaught ReflectionException: Class "Carbon\Carbon" does not exist	Same root cause, surfaced only because a ReflectionClass() call happened before instantiation	Load the autoloader (§2)
E3	Package installed into vendor/ instead of modules/ and the module 404s	The package's type was not claimed by any installer	§9 — either an installer plugin, or keep the module in the app and require the package normally
E4	Access denied: assets must be in subdirectories (403) for a packaged module	The module directory name contained _module (e.g. Invoice_module), which collides with the default MODULE_ASSETS_TRIGGER (_module)	Rename the module/package so its Trongate module name contains no _module (here: Invoices)
E5	composer require aborted non-interactively	Composer 2 requires plugins to be allowlisted	composer config allow-plugins.<vendor>/<plugin> true (or --no-plugins where the plugin is not needed)
E6	Third-party installer package oomphinc/composer-installers-extender is abandoned ("No replacement was suggested")	—	Do not depend on it; a ~40-line self-written plugin does the job (§9)
E7	Path-repo changes (e.g. new extra key) ignored	Composer caches package metadata from the lock file	composer update <vendor>/<package> to refresh; also note composer reinstall reports "does not match any currently installed packages" once an installer moves files outside vendor/
E8	CLI bootstrap died: Failed opening required '../config/config.php'	Trongate uses path-relative requires	chdir() to public/ first (§2 Option C)
E9	Path-repo package invisible only over HTTP (file_exists() = false, CLI fine)	Apache runs with PrivateTmp=yes — a symlinked path repository under /tmp does not exist inside Apache's private tmp namespace	Keep path repositories outside /tmp (e.g. /var/www/html/pkg-repo), or use "symlink": false
E10	Shell-expanded glob when configuring a path repo	Unquoted /path/* expanded by bash before Composer saw it	Quote it: composer config repositories.x path "/path/*"

---

8. Composer configuration that was needed

App composer.json (final, working state):

{
    "name": "trongate/composer-poc",
    "type": "project",
    "require": {
        "php": ">=8.1",
        "dompdf/dompdf": "^3.1",
        "nesbot/carbon": "^3.8",
        "grady-poc/invoice-kit": "^1.0",
        "grady-poc/invoice-module": "^1.0",
        "grady-poc/trongate-installer": "^1.0",
        "grady-poc/reports-module": "^1.0",
        "grady-poc/vat-tools": "^1.0"
    },
    "autoload": {
        "psr-4": { "Trongate\\ComposerDemo\\": "modules/composer_demo/src/" }
    },
    "repositories": [
        { "name": "vcs-demo",   "type": "vcs",  "url": "/var/www/html/vcs-repo/vat-tools" },
        { "name": "local-pkgs", "type": "path", "url": "/var/www/html/pkg-repo/*", "options": { "symlink": true } }
    ],
    "config": {
        "allow-plugins": { "grady-poc/trongate-installer": true }
    }
}

vendor/ is 18 MB / ~1,456 files for Dompdf + Carbon + 4 local packages — a useful number when discussing "does Composer add bloat?"

.gitignore guidance for a Trongate app using Composer: ignore /vendor/, commit composer.json and composer.lock, and ignore any Composer-installed module directory (/modules/invoices/) because it is a build artefact.

---

9. Distributing Trongate modules as Composer (Packagist) packages

This was investigated as a separate question: can a module be shipped as a Composer package rather than copied by hand?

9.1 What works

A module package is an ordinary Composer package whose payload happens to be a Trongate module:

{
    "name": "vendor/invoice-module",
    "description": "A complete Trongate v2 module, distributed as a Composer package.",
    "type": "trongate-module",
    "license": "MIT",
    "require": { "php": ">=8.1", "vendor/invoice-kit": "^1.0" },
    "extra": { "trongate-module-name": "invoices" }
}

with Invoices.php (controller) and views/ at the package root. Verified: two such packages installed and routed at /invoices/ and /reports/, each of them also pulling in a plain library package as a dependency.

9.2 The one missing piece: getting it into modules/

Composer's default installer only understands library-ish types; an unknown type is installed into vendor/ where Trongate cannot see it. Two approaches:

1. composer/installers + oomphinc/composer-installers-extender — the classic route, and it does work, but the extender is abandoned, and it drags a third-party dependency into a framework whose selling point is having none. Not recommended.

2. A tiny self-written installer plugin (recommended). ~40 lines, no dependencies. Verified working (grady-poc/trongate-installer):

   // src/Trongate_installer_plugin.php
   namespace GradyPoc\TrongateInstaller;
   
   use Composer\Composer;
   use Composer\IO\IOInterface;
   use Composer\Plugin\PluginInterface;
   
   class Trongate_installer_plugin implements PluginInterface {
       public function activate(Composer $composer, IOInterface $io): void {
           $composer->getInstallationManager()->addInstaller(new Trongate_module_installer($io, $composer));
       }
       public function deactivate(Composer $composer, IOInterface $io): void {}
       public function uninstall(Composer $composer, IOInterface $io): void {}
   }

   // src/Trongate_module_installer.php
   namespace GradyPoc\TrongateInstaller;
   
   use Composer\Installer\LibraryInstaller;
   use Composer\Package\PackageInterface;
   
   class Trongate_module_installer extends LibraryInstaller {
       public function supports(string $packageType): bool {
           return $packageType === 'trongate-module';
       }
       public function getInstallPath(PackageInterface $package): string {
           $extra = $package->getExtra();
           $module_name = $extra['trongate-module-name'] ?? $this->derive_module_name($package->getPrettyName());
           return 'modules/' . $module_name;
       }
       private function derive_module_name(string $package_name): string {
           $bits = explode('/', $package_name);
           $last = str_replace('-module', '', array_pop($bits));
           return str_replace('-', '_', $last);
       }
   }

   Plugin manifest (composer.json of the plugin package): "type": "composer-plugin", "require": { "composer-plugin-api": "^2.0" }, "extra": { "class": "GradyPoc\\TrongateInstaller\\Trongate_installer_plugin" }. Consumers add "allow-plugins": { "vendor/trongate-installer": true }.

   Notes:

   • InstallationManager::addInstaller() is public API (no CustomInstaller capability class is needed — no such capability exists in Composer 2's source, which is why the old class_type: composer-installer route from Composer 1 no longer applies).
   • The package's own extra.trongate-module-name decides the folder name — important, because a module folder is a routing surface (and must not contain _module, see E4).
   • Because the plugin is installed by the same Composer run, it is safest to install the plugin package first, then the module packages.
   • Verified: composer install from scratch on a wiped vendor/ re-creates both module directories and all routes return 200.

9.3 Packagist

• Packagist does not care about type; it only indexes metadata. Versions come from git tags on a public repository.
• composer validate --strict on all four local packages: valid, with a single warning — "The version field is present, it is recommended to leave it out if the package is published on Packagist." So: keep "version" out of packages destined for Packagist; it is only needed for type: path repositories.
• Publishing flow: public VCS repo → submit URL at packagist.org → tag a release → the GitHub webhook (or Packagist's cron) picks it up. There is no composer publish command.
• Consumption from a VCS/git repository (i.e. exactly what Packagist does under the hood) was verified end-to-end by requiring grady-poc/vat-tools:^1.0 from a tagged local git repo — Composer reported Installing grady-poc/vat-tools (v1.0.0): Cloning 89d0ec0c45 and the class was usable over HTTP and CLI.
• For private distribution, the alternatives to Packagist are a private repository (type: path, type: vcs, a Satis/Private Packagist instance), or continue with copy-the-folder — which remains the most Trongate-ish option of all.

9.4 Strategic note for the docs

The framework's own philosophy ("no Composer, no Packagist, runs forever") does not conflict with any of this. Nothing in this investigation required a change to engine/, and a module that ships with require_once APPPATH.'vendor/autoload.php' at the top of its controller works on a pristine core. The honest framing for the docs is: "Trongate never needs Composer; when you choose to use Composer, here is the two-line contract."

---

10. Environment (for reproduction)

• App: /var/www/html/composer_poc — fresh clone of trongate/trongate-framework master, commit 6b0d0f71053c4f8fcd7f456dbb7f1e1c4d24ebaf (#273), Version: 2.2026.0920d.
• Apache 2.4.66 + mod_php 8.4 (PHP 8.4.16), AllowOverride All, DocumentRoot /var/www/html, app reachable at http://localhost/composer_poc/ (root .htaccess → public/, then public/.htaccess → index.php).
• Apache runs with PrivateTmp=yes (relevant to E9).
• Composer 2.10.3 at /home/david/bin/composer; PHP extensions available include gd, zip, dom, xml, mbstring, curl, openssl (Dompdf satisfied).
• No Composer-related changes were made to engine/, ignition.php, Core.php or any other framework file. The only framework-file edit anywhere is the two-line addition to public/index.php (Option A) of the PoC app.
• Test harness extras that remain in the PoC: cli/with_chdir.php, cli/no_chdir.php (deliberate failure demo).

---

11. Security observations

• S1 — Global class shadowing (real hazard). A package that declares a non-namespaced global class colliding with a Trongate class silently replaces it, because Composer's loader is first in the stack. Demonstrated deliberately with a package declaring class File {}: over HTTP, File then resolved to the package's file and the framework's own File methods were gone (method_exists('File','upload') === false). Documentation implication: the existing convention of namespacing all Composer-published code should be stated as a rule, not a preference.
• S2 — .php files under vendor/ are downloadable as plain text via the /vendor/ asset route (Content-Type: text/plain, source echoed). Harmless for public library code, but a hard rule follows: never put credentials, .env-style files, or private keys under vendor/.
• S3 — Wrong MIME for non-CSS assets (.js, fonts, images → text/plain). Functionally works for classic scripts; breaks strict nosniff/module contexts. Framework change candidate (Core::serve_vendor_asset()), not made here.
• S4 — Traversal protection is sound. Literal, single-encoded, double-encoded and absolute-path variants were all rejected with Invalid file path or directory traversal detected. (404 / die). No bypass found.
• S5 — Supply-chain reality. Once Composer is in play, the app inherits the whole transitive dependency tree (Dompdf + Carbon pulled in PHPUnit-adjacent dev deps? — no dev deps here, but symfony/clock, symfony/translation, psr/clock, carbonphp/carbon-doctrine-types came along). The docs page should say plainly that composer.lock must be committed and that composer outdated/composer audit is now part of the maintenance story — a genuine trade-off against the "runs forever" ethos.

---

12. Open questions / decisions for David

1. Recommended placement in the docs: Option A (public/index.php) or Option B (top of the module file)? I would lead with A for "I want to use a package in my app" and present B as "I am shipping a module others will install". Both verified.
2. Should Trongate publish an official installer plugin (trongate/installer, type: composer-plugin, ~40 lines, verified working in §9) so that module packages can be distributed via Composer without anyone touching composer/installers? This is the only piece of new code the ecosystem would need.
3. Framework change candidates (not made): MIME map in serve_vendor_asset(); optionally shipping the vendor/autoload.php include commented-out in public/index.php of the release.
4. Do you want this report posted as a comment on issue Task: Investigate Composer / Packagist / PSR-4 Modules in Trongate v2 #96, or handed to Mike through the pack only?

---

13. Suggested outline for the eventual docs page (hand-over notes for Mike)

Proposed location: 0030Basic_Concepts, immediately after 0015working_with_third_party_libraries.html (that page covers why/when; this one covers how).

1. You do not need Composer. Here is how to use it if you do.
2. Two-line setup: composer require … + one require_once (show Option A, mention Option B for reusable modules).
3. Using a package inside a module: use at the top of the controller/model/view (verbatim snippets from §5).
4. The /vendor/ asset route: how to reference a package's CSS/JS in a view (and the MIME caveat).
5. Packaging your own module for distribution (type: trongate-module + installer plugin); a caution that a module name must not contain _module.
6. Housekeeping: .gitignore, commit the lock file, composer audit.
7. Troubleshooting table — start with E1 ("500 with an empty body almost always means the autoloader was not loaded") and E8 (CLI/cron chdir).

---

Appendix A — PoC file inventory

/var/www/html/composer_poc/            (Trongate v2 app; pristine core + PoC module)
├── composer.json                     (see §8)
├── composer.lock
├── vendor/                           (Composer output; git-ignored)
├── cli/
│   ├── with_chdir.php                (working CLI entry point)
│   └── no_chdir.php                  (deliberate failure demo)
└── modules/
    ├── composer_demo/                (main PoC module)
    │   ├── Composer_demo.php
    │   ├── Composer_demo_model.php
    │   ├── src/Invoice_builder.php   (module's own PSR-4 class)
    │   └── views/{index,psr4,model_check}.php
    ├── composer_self/Composer_self.php   (Option B: require inside the module)
    ├── invoices -> /var/www/html/pkg-repo/invoice-module/   (installed by the plugin)
    └── reports  -> /var/www/html/pkg-repo/reports-module/   (installed by the plugin)

/var/www/html/pkg-repo/               (path repository: local mock of Packagist)
├── invoice-kit/                      type: library,         PSR-4 GradyPoc\InvoiceKit\
├── invoice-module/                   type: trongate-module, extra.trongate-module-name = invoices
├── reports-module/                   type: trongate-module, extra.trongate-module-name = reports
└── trongate-installer/               type: composer-plugin (the installer in §9.2)

/var/www/html/vcs-repo/vat-tools/     (git repo, tagged v1.0.0 — Packagist-style consumption)

Key verbatim sources are reproduced in §§2, 5 and 9.2; the /tmp/poc_files_dump.txt created during the session contains the same file bodies for the controller, model, views, CLI script and package manifests.

Appendix B — Routes on the PoC app

/composer_demo/ · /composer_demo/check (JSON diagnostics, incl. autoloader order) · /composer_demo/dates · /composer_demo/pdf · /composer_demo/psr4 · /composer_demo/kit · /composer_demo/vat · /composer_demo/model_check · /composer_self/ · /invoices/ · /reports/ — all HTTP 200.

Appendix C — Exact reproduction commands

# 0. app
cd /var/www/html && git clone https://github.com/trongate/trongate-framework.git composer_poc
cd /var/www/html/composer_poc

# 1. packages
composer require dompdf/dompdf:^3.1 nesbot/carbon:^3.8

# 2. autoloader — edit public/index.php (Option A, see §2)

# 3. local package repositories (mock Packagist)
composer config repositories.local-pkgs path "/var/www/html/pkg-repo/*"
composer config allow-plugins.grady-poc/trongate-installer true
composer require grady-poc/trongate-installer:^1.0
composer require grady-poc/invoice-module:^1.0 grady-poc/reports-module:^1.0 grady-poc/invoice-kit:^1.0
composer config repositories.vcs-demo vcs /var/www/html/vcs-repo/vat-tools
composer require grady-poc/vat-tools:^1.0

# 4. prove it
curl http://localhost/composer_poc/composer_demo/check
php cli/with_chdir.php

# 5. clean-room reproducibility
rm -rf vendor modules/invoices modules/reports && composer install

---

End of report — Grady 🎩

[grady-trongate]

Handover note for Mike — what to write

The full technical findings are in the report comment above (13 sections, test matrix, error table, verbatim snippets). This note is the short version: what the docs page should say, and the decisions already taken so nothing needs re-litigating.

Everything below was verified by running it — HTTP and CLI — against a fresh clone of the framework (commit 6b0d0f7, version 2.2026.0920d). No framework file was changed anywhere except a two-line addition to public/index.php of the throwaway test app.

The heart of the page: the whole contract in three lines

composer require dompdf/dompdf

public/index.php:

require_once '../engine/ignition.php';
require_once APPPATH . 'vendor/autoload.php';   // <- the only addition
$init = new Core;

modules/invoices/Invoices.php:

<?php
use Dompdf\Dompdf;

class Invoices extends Trongate {
    public function test(): void {
        $dompdf = new Dompdf();
        $dompdf->loadHtml('<h1>Hello from Trongate v2</h1>');
        $dompdf->render();
        header('Content-Type: application/pdf');
        echo $dompdf->output();
    }
}

That is it. Load the autoloader once, then use what you installed. The v1 video's Dompdf walkthrough is still exactly correct in v2.

Points the page must cover

1. Where to load the autoloader — lead with the app entry point (public/index.php). That is the simplest, matches the v1 video, and is what most people want.
2. Alternative placement: the top of the module controller file (require_once APPPATH . 'vendor/autoload.php'; immediately after <?php, before the use statements). Present this as the one to use when giving a module to somebody else — it works on a pristine core. Legal PHP, verified.
3. use statements work in controllers, models and views — all three were tested and return 200. A module file's own class must remain global (class Training extends Trongate), because the framework resolves it by file name.
4. CLI / cron scripts must bootstrap themselves — they need chdir() into public/, the $_SERVER pseudo-variables, and their own require_once of the autoloader. Without the chdir(), Trongate's relative requires fail outright. Worth an explicit code block, because people hit this the first time they use a package from a script.
5. Referencing a package's CSS/JS from a view works — /vendor/... URLs are served by the framework (Core::serve_vendor_asset()), which is what makes JS-heavy packages such as TinyMCE usable without copying files around. Two honest caveats: only .css gets a CSS content type (everything else, including .js, is sent as text/plain — fine for classic <script> tags, wrong for ES modules), and .php files under vendor/ are downloadable as source, so nothing secret should ever live in vendor/.
6. Housekeeping: gitignore /vendor/; commit composer.json and composer.lock; composer audit joins the maintenance routine. Frame it as a real trade-off against "runs forever" rather than pretending it isn't.
7. Troubleshooting (the two that save the most time):
   • A 500 with an empty response body almost always means the autoloader was never loaded — that is its signature.
   • A module folder name must not contain _module — it collides with MODULE_ASSETS_TRIGGER and yields Access denied: assets must be in subdirectories.

Decisions taken (please don't deviate)

• Lead with the public/index.php placement; the module-file variant is second, for module authors.
• Do not publish or recommend an official Trongate Composer installer plugin at this stage. Module-as-Composer-package is genuinely working (it was built and tested), but it should appear only as an advanced, optional note — with the ~40-line installer source in an appendix — not as the recommended way to share a module. The recommended way to share a module remains: copy the folder.
• Do not point readers at composer/installers or oomphinc/composer-installers-extender — the extender is abandoned ("No replacement was suggested"). If that path is ever documented, use the self-written plugin from the report.
• Keep the framing: Trongate never needs Composer. This page is "if you want it, here is the two-line contract", not "Trongate now has a package ecosystem".

Suggested location

0030Basic_Concepts, immediately after 0015working_with_third_party_libraries.html. That existing page answers why / when — this one answers how, and the two read naturally as a pair.

Runnable code

The complete proof of concept — all three autoloader placements, the module-own PSR-4 class, a mock Packagist with two module packages, the optional installer plugin, and the CLI entry point — has been committed to the exchange repo under For_mike/composer-poc/. Every snippet needed for the page is also inline in the report above, so the page can be written without it.

[grady-trongate]

Notes for Mike — how to write this page

The two comments above are reference material. Do not try to work every finding into the page. The report is there so you can check facts, not so you can summarise it. Aim for one short page — roughly 600 to 800 words and no more than three code blocks.

Suggested title

Using Composer Packages

Alternative if you prefer symmetry with its neighbour (0015working_with_third_party_libraries.html): Working With Composer Packages.

Where it goes

assets/php_framework/0030Basic_Concepts/ — suggested file name 0016using_composer_packages.html, so it sits immediately after "Working With Third-Party Libraries". That page answers why and when; yours answers how. Read as a pair, they need no other explanation.

Suggested structure (five short sections)

1. Composer Is Optional — two or three sentences. Trongate never needs Composer. This page is for when you choose to use it.
2. Install and Load a Package — composer require dompdf/dompdf, then the single line added to public/index.php: require_once APPPATH . 'vendor/autoload.php';. Show both together as one small block.
3. Use It In Your Module — the use Dompdf\Dompdf; line and a five-line method that renders a PDF. That is the whole contract; say so.
4. Two Other Places That Line Goes — keep it to two short subsections: at the top of a module file (for when you give a module to somebody else) and in a CLI or cron script (which needs its own bootstrap).
5. When Things Go Wrong — just two items: a 500 with an empty body means the autoloader was not loaded, and a module folder name must not contain _module.

Then finish with a short closing box (two or three sentences, alert alert-info): you can also ship a whole module as a Composer package — it works, but it is optional and advanced; the simple way to share a module is still to copy the folder.

What to leave out

The installer plugin source, Packagist tagging, the security deep-dive, the test matrix and the MIME-type nuances. All of that stays in the report for anyone who asks a harder question later. If you want one sentence about package assets, it is enough to say that a package's CSS and JS can be referenced straight from /vendor/.

Write it your way

Please write this in the same voice and format as the pages around it — raw HTML fragment, [meta-description] at the top, <h1>/<h2>, [code=php] blocks, the occasional alert box, short sentences, second person, and the same light touch the existing pages use. The report is deliberately drier than the documentation should be; the personality is yours to supply. If a detail in the report contradicts what reads better for the page, write the page and note the discrepancy in a comment here — I will verify it.