PHPackages eril/uri-mapper - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [CLI & Console](/categories/cli) 4. / 5. eril/uri-mapper ActiveLibrary[CLI & Console](/categories/cli) eril/uri-mapper =============== A lightweight CLI tool to generate a named URI catalog from the filesystem, with stable IDs, aliases, and optional recursive index mapping. v1.0.0(4mo ago)011MITPHPPHP >=8.1CI passing Since Dec 24Pushed 4mo agoCompare [ Source](https://github.com/erilshackle/php-uri-mapper)[ Packagist](https://packagist.org/packages/eril/uri-mapper)[ RSS](/packages/eril-uri-mapper/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (1)DependenciesVersions (2)Used By (0) PHP - URI Mapper ================ [](#php---uri-mapper) URI Mapper is a lightweight CLI tool that generates a **named URI catalog** from a filesystem structure. It is designed to help developers reference **important entry-point URIs** in a stable, explicit, and refactor-friendly way — without acting as a router or imposing architectural decisions. This tool does **not** handle HTTP dispatching, request matching, or middleware. It only maps filesystem paths to **named URIs** and generates a small helper class for convenience. --- Why URI Mapper? --------------- [](#why-uri-mapper) In many projects, URIs are managed manually — and that is often the right choice. However, some URIs are: - referenced frequently, - shared across the application, - or expensive to refactor when paths change. URI Mapper helps in these cases by providing: - stable identifiers for key URIs, - safe refactoring through aliases, - and a small helper API to build paths consistently. It is **opt-in by design**: you decide how much or how little you want it to map. --- Features -------- [](#features) - Stable URI IDs via `@route` annotations - Automatic aliases for backward compatibility - Index-only mode for clean, folder-based mappings (`--index`) - Optional `.php` preservation in generated URIs (`--php`) - Explicit URI composition via relative paths - Zero runtime dependencies - No routing, no dispatching, no framework coupling --- Installation ------------ [](#installation) ``` composer require eril/uri-mapper ``` --- Basic Usage ----------- [](#basic-usage) Run the mapper against a directory containing your route files: ``` # vendor/bin/uri-mapper [options] ``` ``` vendor/bin/uri-mapper ./routes ``` This will generate a `Uri.php` helper class containing named URI constants. --- Filesystem Mapping ------------------ [](#filesystem-mapping) Given the following structure: ``` routes/ ├── index.php ├── services/ │ └── index.php ├── admin/ │ ├── index.php │ └── users.php ``` The generated class will expose named URIs such as: ``` Uri::home(); // / Uri::services(); // /services/ Uri::admin(); // /admin/ ``` --- Named Routes (`@route`) ----------------------- [](#named-routes-route) You can define a stable URI identifier using an annotation at the top of a PHP file: ``` ``` ou ``` ``` This decouples the URI name from the filesystem path. If the path changes later, the identifier remains valid. --- Aliases and Backward Compatibility ---------------------------------- [](#aliases-and-backward-compatibility) When a `@route` annotation is present, the automatically generated name becomes an alias. Example: ``` /login/index.php // @route signin ``` Allows: ``` Uri::signin(); // preferred Uri::login(); // alias, still works ``` This makes refactoring safe and explicit. --- Index-Only Mode (`--index`) --------------------------- [](#index-only-mode---index) By default, all PHP files are considered. To generate **only folder-level URIs**, use: ``` vendor/bin/uri-mapper ./routes --index ``` This produces a cleaner API focused on entry points: ``` Uri::home('services'); // /services/ Uri::admin('users'); // /admin/users/ ``` Without generating leaf routes like `Uri::adminUsers()`. --- Preserving `.php` in URIs (`--php`) ----------------------------------- [](#preserving-php-in-uris---php) By default, generated URIs do not include `.php`. To preserve it: ``` vendor/bin/uri-mapper ./routes --php ``` --- Explicit URI Composition (Relative Paths) ----------------------------------------- [](#explicit-uri-composition-relative-paths) The generated `Uri` helper allows composing URIs explicitly using **relative paths**. This is especially useful when using `--index` and building links in templates. ### Rule [](#rule) > If the first argument starts with `/`, it is treated as a path relative to the base URI. ### Examples [](#examples) ``` Uri::admin('/users'); // /admin/users ``` With parameters: ``` Uri::admin('/users/{id}', ['id' => 1]); // /admin/users/1 ``` Query string: ``` Uri::admin('/users', ['page' => 2]); // /admin/users?page=2 ``` This mechanism performs **simple string substitution only**. It does not define routes, validate parameters, or perform dispatching. --- Output Modes ------------ [](#output-modes) ### Dry Run [](#dry-run) ``` vendor/bin/uri-mapper ./routes --dry-run ``` Generates the catalog without writing files. ### JSON Export [](#json-export) ``` vendor/bin/uri-mapper ./routes --json ``` Outputs the URI map as JSON instead of generating a class. --- Generated Helper Class ---------------------- [](#generated-helper-class) The generated `Uri` class provides: ``` Uri::home(); Uri::admin('users'); Uri::services(['page' => 2]); ``` As well as request helpers: ``` Uri::uri(); // current request URI Uri::url(); // full URL Uri::param(); // GET parameters ``` --- Design Philosophy ----------------- [](#design-philosophy) URI Mapper is intentionally minimal. - It does not replace routers. - It does not enforce patterns. - It does not hide behavior. It exists solely to make **important URIs explicit, stable, and easy to reference**. Use it where it helps — ignore it where it doesn’t. --- License ------- [](#license) MIT © Eril TS Carvalho ### Health Score 34 — LowBetter than 77% of packages Maintenance74 Regular maintenance activity Popularity5 Limited adoption so far Community6 Small or concentrated contributor base Maturity43 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 146d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/7912c97a74168d99f71aea2bb33bf6ed2f85ed0e8c990a41c59b8b4a2f009c9f?d=identicon)[erilshackle](/maintainers/erilshackle) --- Top Contributors [![erilshackle](https://avatars.githubusercontent.com/u/74083037?v=4)](https://github.com/erilshackle "erilshackle (16 commits)") --- Tags uriphpclifilesystemroutingmapper ### Embed Badge ![Health badge](/badges/eril-uri-mapper/health.svg) ``` [![Health](https://phpackages.com/badges/eril-uri-mapper/health.svg)](https://phpackages.com/packages/eril-uri-mapper) ``` ### Alternatives [nunomaduro/termwind It's like Tailwind CSS, but for the console. 2.5k239.8M286](/packages/nunomaduro-termwind)[nunomaduro/laravel-console-task Laravel Console Task is a output method for your Laravel/Laravel Zero commands. 2582.1M11](/packages/nunomaduro-laravel-console-task)[mehrancodes/laravel-harbor A CLI tool to Quickly create On-Demand preview environment for your apps. 9989.0k](/packages/mehrancodes-laravel-harbor)[alecrabbit/php-cli-snake Lightweight cli spinner with zero dependencies 29211.3k5](/packages/alecrabbit-php-cli-snake) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)