Repository navigation
Releases
1.0.0-beta.6 - Align installation and Boost guidance with beta.5 baseline
Changed
- Updated project documentation for the beta.5 release baseline (in the documentation for the 1.0.0-beta.6 cycle, including the “Unreleased” section of
CHANGELOG.mdand related install guidance). - Reordered the documented installation/migration steps so the “clean database” requirement is stated before running the migration command, helping prevent users from applying an incorrect migration sequence.
- Added/clarified guidance for “published variant regeneration,” including when and how this regeneration step should be applied.
User impact
- No direct runtime/code/config/API behavior changes are indicated.
- This release is limited to documentation guidance and the order/clarity of operational steps.
Compatibility / Migration
- Existing users do not need code changes.
- Update your operational runbook/process to follow the clarified step ordering (clean database before migration) and apply the documented published variant regeneration requirement when applicable.
1.0.0-beta.5 - Consolidate Filoquent migrations into a single clean-install baseline
Changed
- Updated the migration strategy to use a single consolidated baseline migration for clean installations.
- The consolidated migration now directly creates the full schema for new installs, including:
- The
filoquent_uploadsledger - The
filoquent_upload_namespacejournal namespace, seeded withid=1and a generated UUID - The
filoquent_owner_tablescoordination schema
- The
- Rollback recovery behavior was aligned with the new baseline structure, including added/updated safety guards based on the consolidated schema’s coordination/pending conditions.
- The published/used migration set is now expected to be exactly one timestamped migration file:
2026_11_12_000000_create_filoquent_tables.php.
Removed
- Deleted the earlier, separate timestamped migrations that previously created or modified these schema components (e.g., upload table creation, journal namespace changes, and owner coordination table creation/normalization).
- As a result, environments that previously relied on those individual migrations to create or evolve tables will no longer receive those incremental changes from the package’s current migration set.
Compatibility / Migration Considerations
- Historical migration-chain upgrades are no longer supported by this development baseline.
- If you are upgrading an existing environment that depended on the older stepwise migrations, you should not expect this consolidated migration to “chain up” from historical states.
- Plan to use an appropriate supported upgrade path or consider starting from a fresh database on the new baseline, as described in the updated documentation/release notes.
- Rollback is explicitly refused when coordination/pending states indicate it would be unsafe to revert (for example, if pending coordination exists, if relevant journal/upload state indicates writers are still active, or if required cleanup/disablement has not occurred).
User Impact
- New installations should have a simpler migration publish/install flow (single migration file) and a consistent ledger/journal/coordination schema created by one baseline migration.
- Upgraders may encounter breaking behavior if they previously relied on the older multi-step migration chain or on rollback sequences tied to those removed migrations.
1.0.0-beta.4 - Add persisted regenerate-missing fallback for typed Assets
Added
- Typed/generic
Assetssupport with improved developer ergonomics for working with variant keys. - Read-only “magic” variant properties and passive
isset()support for variant keys. - Persisted missing-asset regeneration capabilities:
Assets::regenerateMissing(keys, source?)(requires an appropriate modelAssetContext, otherwise throwsFiloquentException).- Optional model-aware regeneration context:
Assetscan now accept anAssetContext.get()can regenerate a missing key on demand when context is present; otherwise it returnsnull.
- Middleware-driven regeneration configuration:
- New
#[RegenerateMissing]attribute for middleware classes to mark them for regeneration and optionally configure a regeneration “source”. - New
src/Support/AssetContextto discover the configured regeneration middleware (via the attribute) and to invoke regeneration on models implementing the required regeneration support.
- New
- Integration of regeneration through casts:
AsFilecasts propagateAssetContextso regeneration can occur based on the Eloquent model and cast key.
- New upload/persistence capabilities to support extension workflows:
PendingUploadextended with optional existing manifest tracking, a list of keys, and a source.FileWriterimprovements:- Centralized middleware validation.
- Normalization of
PendingAssetlists. - Added
storeMissing()to regenerate only missing keys based on an existing manifest.
Persistenceupdates for “extension” uploads:- When
PendingUploadincludes an existing manifest, the process locks for extension, stores only missing files, merges new variants into the parent manifest, updates filing state (including orphan handling), and tracks per-key extensions to influence finish-time behavior.
- When
UploadIntentextension support:- Optional
parentIdwith UUIDv7 validation. - Payload versioning (decode supports versions 1 and 2; encode emits version 1 or 2 accordingly).
- Optional
Changed
- Stricter regeneration and lifecycle safety checks in
HasFiloquenthelpers:- Regeneration requires models to be idle/not-dirty.
- Keys are validated before regeneration.
- Stale data mismatches and unsafe states are rejected (e.g., dirty/stale/borrowed/detached).
- Regeneration requires a non-null middleware when regeneration is needed.
- If saving fails, raw attributes are restored.
- Stricter key validation in
PendingAsset:- Uses an anchored ASCII regex and centralized
validateKey/validateKeyshelpers for consistent handling.
- Uses an anchored ASCII regex and centralized
PendingAsset/PendingUploadand writer persistence flow updated to support more precise missing-key regeneration and merging.
Fixed
- Test stability: disconnect native test DB sessions after lifecycle
- Ensures native database sessions used during the test lifecycle are properly disconnected after lifecycle completion.
- Prevents test pollution/leaks and avoids resource exhaustion or cross-test interference in environments that reuse long-lived processes or native connection pools.
Documentation
- Added/updated typed Assets documentation and guidance related to the new typed/generic Assets usage patterns and regeneration behavior.
Internal Maintenance
- PHPStan installation compatibility fix
- Restricted
phpstan/phpstanconstraint to^2.3.5 <2.3.6for type coverage compatibility. - This helps ensure consistent static analysis results in CI/developer workflows.
- Restricted
Compatibility / Migration Notes
- Regeneration requires an
Assetsinstance created with a suitableAssetContext(derived from middleware + model/attribute). CallingregenerateMissingwithout the proper context will throwFiloquentException. - Middleware configuration is now mediated by the
#[RegenerateMissing]attribute (and optional source selection). Ensure middleware classes are annotated appropriately and cast configurations embed/derive middleware info as expected. - Downgrading to older builds may limit management of committed “extended” upload workflows (older versions may not understand the new persisted extended manifests).
- When using regeneration, models must satisfy the new lifecycle/state constraints (idle/not-dirty); unsafe states are rejected to prevent inconsistent manifests and writes.
Testing
- No test additions or changes were explicitly reported in the provided commit summary.
1.0.0-beta.3 - Add filoquent:status diagnostics command
Added
-
New Artisan command:
php artisan filoquent:status- Provides a read-only operational report of the current Filoquent environment and upload pipeline health.
- Checks include:
- Filesystem accessibility
- Validates access to the configured filesystem and
filoquent.base_path.
- Validates access to the configured filesystem and
- Database upload ledger health
- Reads from the
filoquent_uploadstable and reports per-state upload counts. - Supports
--connectionto select the writer connection used for reading ledger data.
- Reads from the
- Redis upload journal availability
- Verifies Redis connectivity via a probe.
- Reports journal intent counts (using
zcard) scoped via the SQL journal scope for the selected DB connection.
- Filesystem accessibility
- Read-only behavior: the command does not modify files, the
filoquent_uploadsledger, or Redis journal contents.
-
Command registration and supporting internals
- Registered in
FiloquentServiceProvider. - Updated
CommandRun::context()behavior to support status reporting correctly:- Ensures mode metadata is correctly set for
filoquent:status. - Ensures
limitis applied only when--limitis explicitly provided, preventing unintended context side effects for status-related flows.
- Ensures mode metadata is correctly set for
- Registered in
-
Enhanced Redis journal support (for the command)
RedisUploadJournaladds:ping()for Redis connectivity verification.count(scope)for journal intent cardinality viazcard.
- Includes strict validation for the new behaviors.
-
Testing
- Added a
StatusCommandTestsuite covering:- Correct use of the private Redis journal connection.
- Correct counting behavior scoped to the selected ledger scope.
- Guarantees that the command does not mutate local storage, does not add ledger rows, does not leak Redis marker state, and keeps transactional behavior stable.
- Graceful handling when storage backends, ledger rows, or required status inputs are unavailable.
- No credential disclosure in Redis reporting.
- Correct handling of
--connection(including rejecting invalid connection names). --silentbehavior.- Remote storage accessibility via read probes.
- Added a
Changed
- Documentation and beta context updates
- Updated beta/source identity wording to reference
1.0.0-beta.2(clarifying historical development before that point). - Updated documentation targets to
1.0.0-beta.2instead of1.0.0-beta.1. - Updated
AGENTS.mdandCHANGELOG.mdrestructuring to present this capability under Added and improve beta identity/clarity. - Updated
README.mdand related skill docs to align beta targeting. - Updated
resources/boost/skills/filoquent-development/SKILL.mdwith:- Discovery instructions (
php artisan list filoquent) filoquent:statususage and what it reports--connection=uploadsguidance- How to interpret counts
- Operational expectations (including that credentials/adapter exception text are omitted)
- Discovery instructions (
- Updated beta/source identity wording to reference
Behavior notes (user-visible)
-
Exit status reliability
- Returns
SUCCESSonly when all relevant checks succeed (filesystem, ledger, and Redis journal). - Otherwise returns
FAILURE.
- Returns
-
Availability/error signaling
- When checks are unavailable, the command emits issue-key style identifiers such as:
status_filesystem_unavailablestatus_ledger_unavailablestatus_journal_unavailablestatus_journal_count_unavailable
- Includes suggested remediation actions.
- When checks are unavailable, the command emits issue-key style identifiers such as:
Compatibility
- This release primarily introduces a new read-only diagnostic capability (
filoquent:status). - Internal context handling for
filoquent:statuswas adjusted to prevent unintendedmode/limitside effects, but no other API-level changes are stated beyond the new command.
Migration / upgrade guidance
- Documentation for this beta release updates upgrade/target guidance to reference
1.0.0-beta.2. - As with beta artifacts, wording and behavior may continue to change prior to the stable
1.0.0release.
1.0.0-beta.2 - Add middleware generator and native file attributes with persisted state enums
Added
-
New Artisan generator command:
php artisan filoquent:make-middleware {name} {--force}- Implemented in
src/Console/Commands/MakeMiddlewareCommand.php. - Generates a Filoquent upload middleware class using the new stub template
resources/stubs/middleware.stub. - Generated namespace default:
<rootNamespace>\Files. - The generated middleware includes a
handle(Upload $file)method that delegates to$file->asset()and returns:- a
PendingAsset, or - a non-empty list of results depending on what the upload resolves to.
- a
- Overwrite behavior: pass
--forceto control overwriting existing generated files.
- Implemented in
-
Native File attributes and persisted state enums:
- Introduces native support for File attributes and adds persisted state enums (as provided by commit
3604688).
- Introduces native support for File attributes and adds persisted state enums (as provided by commit
Changed
- Standardized middleware creation for the upload pipeline to align developer workflow with typical Laravel generator conventions.
Notes / Migration
- To use the new middleware generator, run the new Artisan command to create the middleware class. Use
--forceif you intend to overwrite an existing middleware file.
1.0.0-beta.1 - Update beta release documentation and prerelease installation instructions
Changed
-
CHANGELOG.md
- Added/updated a Changed entry describing the beta documentation updates.
- Documented the updated Packagist installation approach (without requiring a local checkout).
- Noted that maintainers may need to preserve version identifiers for later setup.
-
README.md
- Updated maintainer/badge status from “Preview” → “Beta”.
- Refined the README head description from “Preview file attributes…” → “File attributes…”.
- Revised setup/requirements guidance to clarify that the prerelease is available on Packagist under the beta channel.
- Added a warning that APIs may change before the stable release.
- Updated Composer installation instructions to switch from a local path repository + dev requirement workflow to requiring a specific prerelease version via Packagist:
composer require artisan-toolbox/filoquent:1.0.0-alpha.1
-
Skill documentation (
resources/boost/skills/filoquent-development/SKILL.md)- Replaced instructions that targeted an unpublished dev preview (including references to identity/version and specific PHP/Laravel constraints) with guidance for the published prerelease.
- Kept the API-change warning for the beta/prerelease period.
- Removed the custom Composer path repository setup guidance.
- Updated Composer installation guidance to the direct, version-pinned Packagist approach:
composer require artisan-toolbox/filoquent:1.0.0-alpha.1
Testing
- Updated
tests/Unit/ReadmeHeadTest.phpexpectations so automated checks match the revised README head metadata (e.g., Preview → Beta badge text/image alt metadata and the updated head description).
1.0.0-alpha.1 - Stabilize CI/static analysis and expand validation coverage
Changed
-
Updated CI workflow coverage (SQLite + native DBs): Expanded the test workflow to run additional database scenarios, specifically SQLite and native DBs, to catch DB-specific regressions earlier.
-
Aligned PHPStan parallelism on Windows: Adjusted PHPStan configuration to limit parallelism on Windows by using a shared platform profile. This reduces the likelihood of platform-specific resource contention or configuration issues that can cause PHPStan failures or instability in Windows-based CI.
-
Maintainer checks can validate new source version: Updated the maintainer-checks behavior so that they can validate new source versions.
-
Development workflow pinned to the 1.x line: Updated the Filoquent development workflows to use the 1.x series to better align dev dependency expectations with the intended major version.
Added
- AI and documentation skills standards: Added and/or updated repository standards for AI and documentation skills, including guidance around skill definition and authoring/review workflows, to keep documentation/skill instructions consistent with actual behavior.
Fixed
-
PHPStan reliability on Windows: Limited PHPStan parallelism on Windows to improve static-analysis stability in Windows CI runs.
-
Maintainer validation for new source versions: Ensured maintainer checks can validate new source revisions.
Internal Maintenance
- Repository bootstrap: Initial commit establishes the base project structure.
Compatibility / Migration Notes
- End users: No direct runtime/API changes are described in these changes.
- Contributors / maintainers:
- CI runs may take longer due to the expanded database test matrix (SQLite + native DBs).
- If you run PHPStan locally or in Windows CI, expect improved stability from the Windows parallelism change.
- For development workflows using Filoquent, ensure your local setup aligns with the updated 1.x workflow expectations.
- When updating documentation or agent/skill content, follow the newly added AI/documentation skills standards files.