An independent PHP slug lifecycle engine with clear boundaries between the slug domain, the Host, URLs, HTTP, and SEO.
Release target: 1.0.0-rc.3, a Pre-Stable Release Candidate.
At qualification, 1.0.0-rc.3 is unpublished and 1.0.0-rc.2 is available through Packagist. No Stable support line is established.
The current public contract is owned by SLUG_PACKAGE_REFERENCE.md. Execution evidence is maintained in GitHub PR and CI history rather than duplicated in this consumer-facing README.
The requirements and examples below are for RC.3.
maatify/php-slug is a standalone PHP library for slug generation, canonicalization, scoped ownership, lifecycle management, aliases, history, resolution, and package-owned PDO MySQL persistence.
- Slug Generation & Canonicalization: Consistent generation and canonicalization through versioned built-in profiles.
- Ownership & Lifecycle: Exact claiming, generated allocation, release, scope transition, atomic transfer, and adoption.
- Aliases & History: Active and retired aliases with immutable lifecycle history.
- Persistence & Concurrency: PDO MySQL-compatible persistence with transactions, CAS, and concurrency guarantees.
- Resolution & Management: Resolution, availability, Scope discovery, Scope operational summaries, operational History windows, and management reads with shared pagination.
- Public Extension: Versioned custom Slug profiles through the public registry path, plus Host-owned reserved-slug policy injection.
| Requirement | Value |
|---|---|
| PHP (Composer) | >=8.4.27 <8.5.0 || >=8.5.12 <9.0.0 |
| Database | PDO MySQL; mysql:8.0.36 is the CI reproducibility target |
| Extensions | ext-filter, ext-intl, ext-mbstring, ext-pdo, ext-pdo_mysql |
| Direct packages | maatify/exceptions ^1.0, maatify/shared-common ^1.0, maatify/php-persistence 1.0.0-rc.2 (temporary RC dependency) |
CI verifies PHP 8.4 and 8.5. Composer also admits newer PHP 8 minors within this range. Each newer minor needs its own security and compatibility evidence before it can be listed as supported.
Built-in profiles require the normalization and transliteration capabilities provided by ext-intl; the package verifies those capabilities at runtime. No exact ICU or Unicode version is required from the consumer.
Once RC.3 is published to Packagist, install the exact target and its Persistence dependency using the following command. Keep your project's minimum-stability set to stable; the two @RC allowances apply to these packages.
composer require maatify/php-slug:1.0.0-rc.3@RC maatify/php-persistence:1.0.0-rc.2@RCUpgrading from RC.2. Stop Slug traffic and apply the additive 003_registry_lock_projection.sql migration before enabling the RC.3 persisted runtime. Follow the schema upgrade guide for the backfill and verification steps. Update any pagination imports from the retired maatify/persistence dependency to the types from maatify/php-persistence.
1.0.0-rc.2 was the published version at RC.3 qualification. To install that exact earlier version:
composer require maatify/php-slug:1.0.0-rc.2@RCUse the versioned RC.2 usage guide.
The stateless path does not require a database or Host framework:
$profiles = SlugProfileRegistryFactory::createBuiltIn();
$text = SlugTextServiceFactory::create($profiles);
$slug = $text->generateFromSource(
new SlugProfileKey('ascii-v1'),
'Hello, World!',
);
// $slug->slug->value === 'hello-world'For the persisted path, the Host injects a PDO connection, a ReservedSlugPolicyInterface, and a ClockInterface into SlugEngineFactory::create(...). See docs/guides/USAGE_GUIDE.md for the complete workflow.
The public Runtime provides actual paths for:
- canonicalization through
SlugTextServiceInterface,generateFromSource,canonicalizeClaim, andcanonicalizeLookup; - lifecycle ownership through
SlugEngineandSlugLifecycleServiceInterface, includingassignExact; - consumer reads through
checkAvailability,getCurrent, andresolve; and - management reads through
SlugManagementQueryInterface, includingsearchScopes,getScopeOperationalSummary, andsearchHistory.
This overview does not replace the complete inventory and contracts in SLUG_PACKAGE_REFERENCE.md.
examples/canonicalization.php: a stateless generation and canonicalization example.examples/custom-profile.php: a stateless custom profile registration and usage example.examples/persisted-lifecycle.php: a persisted MySQL lifecycle example using the canonical Compose flow.
The canonicalization and custom-profile examples run without Docker. Run the persisted example from a repository checkout using the examples smoke verification.
docs/guides/USAGE_GUIDE.md— consumer usage and integration.examples/— runnable consumer examples.SLUG_PACKAGE_REFERENCE.md— the current public contract and Public API reference.CHANGELOG.md— change history and publication state.SECURITY.md— security policy and reporting route.CONTRIBUTING.md— development setup and verification commands.README_AR.md— non-canonical Arabic translation of this README.
On the persisted path, the package owns the transaction when the Host has no outer transaction and uses a savepoint when participating in an outer transaction where the capability is supported. Exact claims rely on the unique Registry constraint as the final race authority and use lifecycle mutation CAS and idempotency according to the contract. See SLUG_PACKAGE_REFERENCE.md for the normative details.
The Host owns the connection, PDO configuration, entity existence, routing, HTTP, SEO, and authorization. The package does not create hidden connections or use Host foreign keys or joins. For vulnerability reports, see Security Policy; do not disclose private vulnerability details through GitHub Issues.
Package-defined semantic and domain failures use the SlugExceptionInterface / SlugDomainExceptionInterface hierarchy described in the Package Reference. External infrastructure Throwable instances, including PDO failures outside the documented semantic conversions, may propagate unchanged according to the current contract.
The package is maintained behind the repository's configured CI and quality gates. Current execution evidence is maintained in GitHub PR and CI history.
For repository setup, tests, and example gates, see CONTRIBUTING.md. The persisted example uses the checkout’s disposable MySQL service.
Licensed under the MIT License.
Engineered by Mohamed Abdulalim (@megyptm)
Backend Lead & Technical Architect
https://www.maatify.dev