Retrieving Entities

Once you have an entity and its associated database table you can start retrieving data from your database.

Active Record

You start every interaction with Quick with an instance of an entity. The easiest way to do this is using WireBox. getInstance is available in all handlers by default. WireBox can easily be injected in to any other class you need using inject="wirebox".

Quick is backed by qb, a CFML Query Builder. With this in mind, think of retrieving records for your entities like interacting with qb. For example:

In addition to using for you can utilize the each function on arrays. For example:

You can add constraints to the query just the same as you would using qb directly:

Quick Service

A second way to retrieve results is to use a Quick Service. It is similar to a VirtualEntityService from cborm.

The easiest way to create a Quick Service is to inject it using the quickService: dsl:

If you have a existing Service, and you would like to extend the quickService, you can extend the quikc.models.BaseService and then call super.init inside of the service init function passing the name of the entity (for example your User Entity) shown below:

Any method you can call on an entity can be called on the service. A new entity will be used for all calls to a Quick Service.

Aggregates

Calling qb's aggregate methods (count, max, etc.) will return the appropriate value instead of an entity or collection of entities.

existsOrFail

Returns true if any entities exist with the configured query. If no entities exist, it throws an EntityNotFound exception.

Retrieval Methods

all

Retrieves all the records for an entity. Calling all will ignore any non-global constraints on the query.

get

Executes the configured query, eager loads any relations, and returns the entities in a new collection.

paginate

Executes the configured query, eager loads any relations, and returns the entities in the configured qb pagination struct.

simplePaginate

Executes the configured query, eager loads any relations, and returns the entities in the configured qb simple pagination struct.

first

Executes the configured query and returns the first entity found. If no entity is found, returns null.

firstWhere

Adds a basic where clause to the query and returns the first result.

firstOrFail

Executes the configured query and returns the first entity found. If no entity is found, then an EntityNotFound exception is thrown with the given or default error message.

firstOrNew

Finds the first matching record or returns an unloaded new entity.

firstOrCreate

Finds the first matching record or creates a new entity.

find

Returns the entity with the id value as the primary key. If no record is found, it returns null instead.

findOrFail

Returns the entity with the id value as the primary key. If no record is found, it throws an EntityNotFound exception.

findOrNew

Returns the entity with the id value as the primary key. If no record is found, it returns a new unloaded entity.

findOrCreate

Returns the entity with the id value as the primary key. If no record is found, it returns a newly created entity.

newEntity

You will probably not use newEntity very often if you use wirebox getinstance("someQuickEntity") to retrieve an entity, because that will already give you a new entity. If you are using a QuickService you will need this method for creating a new entity

Hydration Methods

Hydration is a term to describe filling an entity with a struct of data and then marking it as loaded, without doing any database queries. For example, this might be useful when hydrating a user from session data instead of doing a query every request.

hydrate

Hyrdates an entity from a struct of data. Hydrating an entity fills the entity and then marks it as loaded.

If the entity's keys are not included in the struct of data, a MissingHydrationKey is thrown.

hydrateAll

Hydrates a new collection of entities from an array of structs.

Custom Collections

If you would like collections of entities to be returned as something besides an array, you can override the newCollection method. It receives the array of entities. You can return any custom collection you desire.

newCollection

Returns a new collection of the given entities. It is expected to override this method in your entity if you need to specify a different collection to return. You can also call this method with no arguments to get an empty collection.