Download the PHP package componenta/cycle without Composer

Componenta Cycle

Runtime integration between Componenta framework libraries and Cycle ORM/DBAL. The package provides repository base classes, data fetcher helpers, query filter contracts, typecasts, config provider factories, and database-oriented read models.

Discovery and console integration live in componenta/cycle-app.

Installation

Install componenta/cycle-app only when an application needs entity discovery, schema-related console commands, or framework cache integration.

Related Packages

Repository Layer

Repository extends Cycle ORM repositories and gives application repositories a common framework base without forcing domain code to depend on the application runtime.

Use repositories for aggregate persistence and identity-based lookups. Keep business transitions in aggregates and handlers; repositories should not become policy or workflow services.

Data Fetchers

DataFetcher is a read-side helper for list/detail projections built on Cycle DBAL. It provides:

• table name derivation with override support
• column selection through query interfaces
• pagination and optional total counts
• sort filters
• field mapping from snake_case to camelCase
• per-field casters
• mapper methods named as map{FieldName}
• batch relation helpers for belongs-to, has-many, and many-to-many reads

Fetcher methods transform database rows into arrays or projection objects. Relation loading is batched after rows are collected, so fetchers can avoid N+1 queries.

Query Contracts

Read query objects can opt into behavior by implementing small contracts:

RequiresTotalCountInterface controls whether the paginator exposes the total. Without it, totalCount is null and hasNextPage still reports whether another page exists.

Fetcher Extension Points

Application fetchers usually extend DataFetcher and customize it with protected properties and methods:

Standard filters include PaginationFilter, OrderFilter, SearchFilter, DateRangeFilter, DateTimeFilter, ComparisonFilter, BetweenFilter, InFilter, NotInFilter, NullFilter, NotNullFilter, BooleanFilter, and SoftDeleteFilter.

Typecasts And Factories

The package includes framework typecasts and factory services used to configure Cycle ORM integration. These are runtime pieces and can be wired manually or through the Componenta DI config provider.

Built-in typecasts are UuidTypecast, EnumTypecast, and CarbonTypecast.

ConfigProvider registers Cycle DBAL/ORM factories for database configuration, database manager, ORM, schema, entity manager, migrations, and the default core factory. The main config keys live in ConfigKey.

Performance Notes

DataFetcher caches mapper-method names per instance and reads the current relation selection from the query. Requested totals use an aggregate over the unpaginated selection. Without a total, a limited query checks for one result after the page: ordinary selections use EXISTS, while DISTINCT, grouping and set operations retain their result cardinality in a limited count query. MySQL and SQL Server describe the output width before derived-table counts, assigning unique column aliases for stars and duplicate names. The page query selects only the requested rows. Page fields pass through unchanged to row transformation. The fetcher closes its statements before loading relations, including when reading or transforming a row fails.

The default database configuration uses the native SQL compiler. Query compilation caching is disabled because the upstream cache can change parameter binding for compound queries.

Pagination tests use SQLite in memory by default. To run the same public-contract tests on another supported database, set CYCLE_TEST_DB_DRIVER, CYCLE_TEST_DB_NAME and the required CYCLE_TEST_DB_HOST, CYCLE_TEST_DB_PORT, CYCLE_TEST_DB_USER, CYCLE_TEST_DB_PASSWORD or CYCLE_TEST_DB_SCHEMA variables, then run tests/DataFetcherPaginationTest.php. These tests select literal rows and do not create or modify tables.

tests/DataFetcherCursorTest.php uses the same MySQL connection variables to verify unbuffered reads, query caching, relation loading and recovery after row-conversion exceptions. It is skipped when a MySQL test connection has not been configured.

Boundaries

componenta/cycle contains runtime database behavior. Filesystem scanning, attribute discovery, schema console commands, and compile integration belong to componenta/cycle-app.