Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
To get started with Quick, you need an entity. You start by extending quick.models.BaseEntity.
That's all that is needed to get started with Quick. There are a few defaults of Quick worth mentioning here.
You can generate Quick entities from CommandBox! Install quick-commands and use quick entity create to get started!
We don't need to tell Quick what table name to use for our entity. By default, Quick uses the pluralized, snake_cased name of the component for the table name. That means for our User entity Quick will assume the table name is users. For an entity with multiple words like PasswordResetToken the default table would be password_reset_tokens. You can override this by specifying a table metadata attribute on the component.
For more information on using inheritance and child tables in your relational database model, see Subclass Entities.
By default, Quick assumes a primary key of id. The name of this key can be configured by setting variables._key in your component.
Quick also assumes a key type that is auto-incrementing. If you would like a different key type, override thekeyType function and return the desired key type from that function.
Quick ships with the following key types:
AutoIncrementingKeyType
NullKeyType
ReturningKeyType
UUIDKeyType
RowIDKeyType
keyType can be any component that adheres to the keyType interface, so feel free to create your own and distribute them via ForgeBox.
Quick also supports compound or composite keys as a primary key. Define your variables._key as an array of the composite keys:
Note that your chosen keyType will need to be able to handle composite keys.
You specify what attributes are retrieved by adding properties to your component.
Now, only the id, username, and email attributes will be retrieved.
Make sure to include the primary key (id by default) as a property.
To prevent Quick from mapping a property to a database column add the persistent="false" attribute to the property. This is needed mostly when using dependency injection.
If the column name in your table is not the column name you wish to use in Quick, you can specify the column name using the column metadata attribute. The attribute will be available using the name of the attribute.
To work around CFML's lack of null, you can use the nullValue and convertToNull attributes.
nullValue defines the value that is considered null for a attribute. By default it is an empty string. ("")
convertToNull is a flag that, when false, will not try to insert null in to the database. By default this flag is true.
The readOnly attribute will prevent setters, updates, and inserts to a attribute when set to true.
In some cases you will need to specify an exact SQL type for your attribute. Any value set for the sqltype attribute will be used when inserting or updating the attribute in the database. It will also be used when you use the attribute in a where constraint.
The casts attribute allows you to use a value in your CFML code as a certain type while being a different type in the database. A common example of this is a boolean which is usually represented as a BIT in the database.
Two casters ship with Quick: BooleanCast@quick and JsonCast@quick. You can add them using those mappings to any applicable columns.
The casts attribute must point to a WireBox mapping that resolves to a component that implements the quick.models.Casts.CastsAttribute interface. (The implements keyword is optional.) This component defines how to get a value from the database in to the casted value and how to set a casted value back to the database. Below is an example of the built-in BooleanCast, which comes bundled with Quick.
Casted values are lazily loaded and cached for the lifecycle of the component. Only cast values that have been loaded will have set called on them when persisting to the database.
Casts can be composed of multiple fields as well. Take this Address value object, for example:
This component is not a Quick entity. Instead it represents a combination of fields stored on our User entity:
Noticed that the casted address is neither persistent nor does it have a getter or setter created for it.
The last piece of the puzzle is our AddressCast component that handles casting the value to and from the native database values:
You can see that returning a struct of values from the set function assigns multiple attributes from a single cast.
You can prevent inserting and updating a property by setting the insert or update attribute to false.
Quick handles formula, computed, or subselect properties using query scopes and the addSubselect helper method. Check out the docs in query scopes to learn more.
Quick uses a default datasource and default grammar, as described here. If you are using multiple datasources you can override default datasource by specifying a datasource metadata attribute on the component. If your extra datasource has a different grammar you can override your grammar as well by specifying a grammar attribute.
At the time of writing Valid grammar options are: MySQLGrammar@qb, PostgresGrammar@qb, SqlServerGrammar@qb and OracleGrammar@qb. Please check the qb docs for additional options.
You can compare entities using the isSameAs and isNotSameAs methods. Each method takes another entity and returns true if the two objects represent the same entity.
Checks if the entity was loaded from the database.
| Name | Type | Required | Default | Description |
|---|
A loaded entity has a tie to the database. It has either been loaded from the database or saved to the database. An unloaded entity is one created in code but not saved to the database yet.
Clones the entity and returns an exact copy of the entity.
| Name | Type | Required | Default | Description |
|---|
Clones an entity and return an exact copy of the entity. This returned object is a new and separate instance from the original object.
No parameters |
markLoaded | boolean | false | false | Mark the returned entity as loaded or not |
qb is the engine that powers Quick. It is highly recommended that you become familiar with the qb documentation.
You can do this any way you'd like: through the web admin, in Application.cfc, or using cfconfig.
Make sure to set this.datasource in your Application.cfc so Quick knows which datasource to use.
Quick can use multiple datasources, but it makes it easier to use when you don't have to deal with that.
The easiest way to download Quick is to use ForgeBox with CommandBox. Just run the following from the root of your application:
box install quick
quick in your Application.cfcFor a default installation in a ColdBox template, the following line will do the trick.
this.mappings[ "/quick" ] = COLDBOX_APP_ROOT_PATH & "/modules/quick";
defaultGrammar in config/ColdBox.cfcQuick will auto discover your grammar by default on startup. To avoid this check, set a BaseGrammar.
defaultGrammar is a module setting for Quick. Set it in your config/ColdBox.cfc like so:
Valid options are any of the qb supported grammars. At the time of writing valid grammar options are: MySQLGrammar@qb, PostgresGrammar@qb, SqlServerGrammar@qb and OracleGrammar@qb. You can also have qb discover your grammar on application init using AutoDiscover@qb. Please check the qb docs for additional options.
If you want to use a different datasource and/or grammar for individual entitities you can do so by adding some metadata attributes to your entities.
By default, Quick supports basic component-level inheritance of entities, meaning that a child component inherits the properties ( and ability to overload ) its parent. A common, object-oriented relational database pattern, however is to provide additional definition on parent tables ( and classes ) within child tables which contain a foreign key.
Quick supports two types of child classes: Discriminated and Subclassed child entities. In both cases, loading any child class will also deliver the data of its parent class.
Let's say, for example, that I have a Media entity, which is used to catalog and organize all media items loaded in to my application.
My Media entity contains all of the properties which are common to every media item uploaded in to my application. Let's say, however, that I need to have specific attributes that are available on only media for my Book entity ( e.g. whether the image is the cover photo, for example ). I can create a child class of BookMedia which extends my Media entity. When loaded, all of the properties of Media will be loaded along with the custom attributes which apply to my BookMedia object:
Note the additional component attribute joincolumn. The presence of this attribute on a child class signifies that it is a child entity of the parent and that the parent's properties should be loaded whenever the BookMedia entity is loaded. In addition, the primary key of the entity is that of the parent.
Note that a table attribute is required on a child entity if the parent entity has one. This is because ColdBox will perform a deep merge on the entire inheritance chain for metadata properties. If a parent class has a table attribute, it will show up as the child's table attribute.
Child entities can be retrieved by queries specific to their own properties:
Or properties on the parent class can be used as first-class properties within the query:
Child entities can be retrieved, individually, using the value of the joinColumn, which should be a foreign key to the parent identifier column:
Now my Book entity can use its extended media class to retrieve media items which are specific to its own purpose:
A discriminated child class functions, basically, in the same way as a subclassed entity, with one exception: The parent entity is aware of the discriminated child due to a discriminatorValue attribute and will return a specific subclass when a retrieval is performed through the parent Entity. This pattern is also known as polymorphic association.
Quick supports two different types of discriminated entities defined by single-table inheritance (STI) or multi-table inheritance (MTI). Your database schema will determine the most appropriate inheritance pattern for your use case.
Let's take our BookMedia class again, but this time, define it as a discriminated entity.
The first step is to add the discriminatorColumn attribute to the Media entity, which is used to differentiate the subclass entities. Next, define an array of possible discriminated entities for the parent. This is so we don't have to scan all Quick components just to determine if there are any discriminated entities.
Then we set a discriminatorValue property on the child class, the value of which is stored in the parent entity table, which differentiates the different subclasses.
Then we set a discriminatorValue property on the child class, the value of which is stored in the parent entity table:
We aren’t entirely done yet. Finally, we must tell Quick whether we are using multi-table inheritance or single-table inheritance so it can map the database data to the subclass entities.
If the data for your discriminated entities is normalized across multiple tables, you should use the multi-table inheritance (MTI) method for creating discriminated entities. In the example below, The Media entity has two subclasses, MediaBook and MediaAlbum. The discriminator column for the entities is the type column in the media table and the distinct properties for each subclass come from the media_book and media_album tables.
To inform Quick that our database schema follows the MTI pattern, we must add a joinColumn and table values for each subclass.
If the data for your discriminated entities lives in a single table, you should use the single-table inheritance (STI) method for creating discriminated entities. In the example below, the Media entity has two subclasses, MediaBook and MediaAlbum. The discriminator column for the entities is the type column in the media table, and the distinct properties for each subclass come from a single table.
To inform Quick that our database schema follows the STI pattern, we must also add singleTableInheritance=true to the parent entity.
Once the parent and child entities are defined, new BookMedia entities will be saved with a type value of "book" in the media table. As such, the following query will result in only entities of BookMedia being returned:
If our Media table contains a combination of non-book and book media, then the collection returned when querying all records will contain a mix of Media entities such as BookMedia and AlbumMedia
If you want to create a brand-new entity of a specific subclass, you can do so by calling newChildEntity( discriminatorValue ) like this:
Discriminated and child class entities, allow for a more Object oriented approach to entity-specific relationships by allowing you to eliminate pivot/join tables and extend the attributes of the base class.
Once you have an entity and its associated database table you can start retrieving data from your database.
You can configure your query to retrieve entities using any qb method. It is highly recommended you become familiar with the qb documentation.
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:
For more information on what is possible with qb, check out the qb documentation.
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.
If you need a new unsaved entity from your service, you can call myService.newEntity()
Calling qb's aggregate methods (count, max, etc.) will return the appropriate value instead of an entity or collection of entities.
Returns true if any entities exist with the configured query. If no entities exist, it throws an EntityNotFound exception.
Retrieves all the records for an entity. Calling all will ignore any non-global constraints on the query.
Executes the configured query, eager loads any relations, and returns the entities in a new collection.
Executes the configured query, eager loads any relations, and returns the entities in the configured qb pagination struct.
Executes the configured query, eager loads any relations, and returns the entities in the configured qb simple pagination struct.
Executes the configured query and returns the first entity found. If no entity is found, returns null.
Adds a basic where clause to the query and returns the first result.
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.
Finds the first matching record or returns an unloaded new entity.
Finds the first matching record or creates a new entity.
Returns the entity with the id value as the primary key. If no record is found, it returns null instead.
Returns the entity with the id value as the primary key. If no record is found, it throws an EntityNotFound exception.
Returns the entity with the id value as the primary key. If no record is found, it returns a new unloaded entity.
Returns the entity with the id value as the primary key. If no record is found, it returns a newly created entity.
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 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.
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.
Hydrates a new collection of entities from an array of structs.
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.
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.
New Quick entities can be created and persisted to the database by creating a new entity instance, setting the attributes on the entity, and then calling the save method.
When we call save, the record is persisted from the database and the primary key is set to the auto-generated value (if any).
We can shortcut the setters above using a fill method.
Finds the first matching record or creates a new entity.
Sets attributes data from a struct of key / value pairs. This method does the following, in order:
Guard against read-only attributes.
Attempt to call a relationship setter.
Calls custom attribute setters for attributes that exist.
Throws an error if an attribute does not exist (if ignoreNonExistentAttributes is false which is the default).
Populate is simply an alias for fill. Use whichever one suits you best.
Creates a new entity with the given attributes and then saves the entity.
There is no need to call save when using the create method.
Finds the first matching record or returns an unloaded new entity.
Finds the first matching record or creates a new entity.
Returns the entity with the id value as the primary key. If no record is found, it returns a new unloaded entity.
Returns the entity with the id value as the primary key. If no record is found, it returns a newly created entity.
Updates an existing record or creates a new record with the given attributes.
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.
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.
Hydrates a new collection of entities from an array of structs.
You can delete an entity by calling the delete method on it.
The entity will still exist in any variables you have stored it in, even though it has been deleted from the database.
Just like updateAll, you can delete many records from the database by specifying a query with constraints and then calling the deleteAll method.
Deletes matching entities according to the configured query.
Additionally, you can pass in an array of ids to deleteAll to delete only those ids. Note that any previously configured constraints will still apply.
Updates are handled identically to inserts when using the save method. The only difference is that instead of starting with a new entity, we start with an existing entity.
You can update multiple fields at once using the update method. This is similar to the create method for creating new entities.
There is no need to call save when using the update method.
By default, if you have a key in the struct that doesn't match a property in the entity the update method will fail. If you add the optional argument ignoreNonExistentAttributes set to true, those missing keys are ignored. Now you can pass the rc scope from your submitted form directly into the update method and not worry about any other keys in the rc like event that would cause the method to fail.
Updates an existing record or creates a new record with the given attributes.
Updates matching entities with the given attributes according to the configured query. This is analagous to qb's update method.
Retrieves a new entity from the database with the same key value as the current entity. Useful for seeing any changes made to the record in the database. This function executes a query.
Refreshes the attributes data for the entity with data from the database. This differs from fresh in that it operates on the current entity instead of returning a new one. This function executes a query.
Query scopes are a way to encapsulate query constraints in your entities while giving them readable names .
For instance, let's say that you need to write a report for subscribers to your site. Maybe you track subscribers in a users table with a boolean flag in a subscribed column. Additionally, you want to see the oldest subscribers first. You keep track of when a user subscribed in a subscribedDate column. Your query might look as follows:
Now nothing is wrong with this query. It retrieves the data correctly and you continue on with your day.
Later, you need to retrieve a list of subscribed users for a different part of the site. So, you write a query like this:
We've duplicated the logic for how to retrieve active users now. If the database representation changed, we'd have to change it in multiple places. For instance, what if instead of keeping track of a boolean flag in the database, we just checked that the subscribedDate column wasn't null?
Now we see the problem. Let's look at the solution.
The key here is that we are trying to retrieve subscribed users. Let's add a scope to our User entity for subscribed:
Now, we can use this scope in our query:
We can use this on our first example as well, for our report.
We've successfully encapsulated our concept of a subscribed user!
We can add as many scopes as we'd like. Let's add one for longestSubscribers.
Now our query is as follows:
Best of all, we can reuse those scopes anywhere we see fit without duplicating logic.
All query scopes are methods on an entity that begin with the scope keyword. You call these functions without the scope keyword (as shown above).
Each scope is passed the query, a reference to the current QuickBuilder instance, as the first argument. Any other arguments passed to the scope will be passed in order after that.
All of the examples so far either returned the QuickBuilder object or nothing. Doing so lets you continue to chain methods on your Quick entity. If you instead return a value, Quick will pass on that value to your code. This lets you use scopes as shortcut methods that work on a query.
For example, maybe you have a domain method to reset passwords for a group of users, and you want the count of users updated returned.
Occasionally, you want to apply a scope to each retrieval of an entity. An example of this is an Admin entity which is just a User entity with a type of admin. Global Scopes can be registered in the applyGlobalScopes method on an entity. Inside this entity you can call any number of scopes:
These scopes will be applied to the query without needing to call the scope again.
To temporarily disable global scopes that have been applied to an entity, you have the option to disable them individually or all at once by utilizing the withoutGlobalScope method.
Subselects are a useful way to grab data from related tables without having to execute the full relationship. Sometimes you just want a small piece of information like the lastLoginDate of a user, not the entire Login relationship. Subselects are perfect for this use case. You can even use subselects to provide the correct key for dynamic subselect relationships. We'll show how both work here.
Here's an example of grabbing the lastLoginDate for a User:
We'd add this subselect by calling our scope:
We can even constrain our User entity based on the value of the subselect, so long as we've called the scope adding the subselect first (or made it a global scope).
Or add a new scope to User based on the subselect:
In this example, we are using the addSubselect helper method. Here is that function signature:
You might be wondering why not use the logins relationship? Or even logins().latest().limit( 1 ).get()? Because that executes a second query. Using a subselect we get all the information we need in one query, no matter how many entities we are pulling back.
In most cases the values you want as subselects are values from your entity's relationships. In these cases, you can use a shortcut to define your subselect in terms of your entity's relationships represented as a dot-delimited string.
Let's re-write the above subselect for lastLoginDate for a User using the existing relationship:
Much simpler! In addition to be much simpler this code is also more dynamic and reusable. We have a relationship defined for logins if we need to fetch them. If we change how the logins relationship is structured, we only have one place we need to change.
With the query cleaned up using existing relationships, you might find yourself adding subselects directly in your handlers instead of behind scopes. This is fine in most cases. Keep an eye on how many places you use the subselect in case you need to re-evaluate and move it behind a scope.
Subselects can be used in conjunction with relationships to provide a dynamic, constrained relationship. In this example we will pull the latest post for a user.
This can be executed as follows:
As you can see, we are loading the id of the latest post in a subquery and then using that value to eager load the latestPost relationship. This sequence will only execute two queries, no matter how many records are loaded.
Virtual attributes are attributes that are not present on the table backing the Quick entity. A Subselect is an example of a virtual attribute. Other examples could include calculated counts or CASE statement results.
By default, if you add a virtual column to a Quick query, you won't see anything in the entity. This is because Quick needs to have an attribute defined to map the result to. You can create a virtual attribute in these cases.
This step is unnecessary when using the addSubselect helper method.
Here's an example including the result of a CASE statement as a field:
With this code, we could now access the publishedStatus just like any other attribute. It will not be updated, inserted, or saved though, as it is just a virtual column.
The appendVirtualAttribute method adds the given name as an attribute available in the entity.
Creates a virtual attribute for the given name.
It is likely that Quick will introduce more helper methods in the future making these calls simpler.
Quick handles subselect properties (or computed or formula properties) through query scopes. This allows you to dynamically include a subselect. If you would like to always include a subselect, add it to your entity's
| Argument | Type | Required | Default | Description |
|---|
| Argument | Type | Required | Default | Description |
|---|
Name
Type
Required
Default
Description
attributes
struct
false
{}
A struct of key / value pairs to fill in to the new entity.
ignoreNonExistentAttributes
boolean
false
false
If true, does not throw an exception if an attribute does not exist. Instead, it skips the non-existent attribute.
include
list or array
false
[]
List or array of keys to include when filling. All others will be ignored.
exclude
list or array
false
[]
List or array of keys to exclude when filling. All others will be filled.
Name
Type
Required
Default
Description
attributes
struct
false
{}
A struct of key / value pairs to fill in to the new entity.
ignoreNonExistentAttributes
boolean
false
false
If true, does not throw an exception if an attribute does not exist. Instead, it skips the non-existent attribute.
Name
Type
Required
Default
Description
attributes
struct
false
{}
A struct of key / value pairs to fill in to the new entity.
ignoreNonExistentAttributes
boolean
false
false
If true, does not throw an exception if an attribute does not exist. Instead, it skips the non-existent attribute.
Name
Type
Required
Default
Description
attributes
struct
false
{}
A struct of attributes to restrict the query. If no entity is found the attributes are filled on the new entity returned.
newAttributes
struct
false
{}
A struct of attributes to fill on the new entity if no entity is found. These attributes are combined with attributes.
ignoreNonExistentAttributes
boolean
false
false
If true, does not throw an exception if an attribute does not exist. Instead, it skips the non-existent attribute.
Name
Type
Required
Default
Description
attributes
struct
false
{}
A struct of attributes to restrict the query. If no entity is found the attributes are filled on the new entity created.
newAttributes
struct
false
{}
A struct of attributes to fill on the created entity if no entity is found. These attributes are combined with attributes.
ignoreNonExistentAttributes
boolean
false
false
If true, does not throw an exception if an attribute does not exist. Instead, it skips the non-existent attribute.
Name
Type
Required
Default
Description
id
any
true
The id value to find.
attributes
struct
false
{}
A struct of attributes to fill on the new entity if no entity is found.
ignoreNonExistentAttributes
boolean
false
false
If true, does not throw an exception if an attribute does not exist. Instead, it skips the non-existent attribute.
Name
Type
Required
Default
Description
id
any
true
The id value to find.
attributes
struct
false
{}
A struct of attributes to use when creating the new entity if no entity is found.
ignoreNonExistentAttributes
boolean
false
false
If true, does not throw an exception if an attribute does not exist. Instead, it skips the non-existent attribute.
Name
Type
Required
Default
Description
attributes
struct
false
{}
A struct of attributes to restrict the query. If no entity is found the attributes are filled on the new entity created.
newAttributes
struct
false
{}
A struct of attributes to update on the found entity or the new entity if no entity is found.
ignoreNonExistentAttributes
boolean
false
false
If true, does not throw an exception if an attribute does not exist. Instead, it skips the non-existent attribute.
Name
Type
Required
Default
Description
attributes
struct
false
{}
A struct of key / value pairs to fill in to the entity.
ignoreNonExistentAttributes
boolean
false
false
If true, does not throw an exception if an attribute does not exist. Instead, it skips the non-existent attribute.
Name
Type
Required
Default
Description
mementos
array
false
[]
An array of structs to hydrate into entities.
ignoreNonExistentAttributes
boolean
false
false
If true, does not throw an exception if an attribute does not exist. Instead, it skips the non-existent attribute.
Name
Type
Required
Default
Description
id
any
false
An optional id to check if it exists.
errorMessage
any
false
"No [#entityName()#] found with id [#arguments.id#]"
An optional string error message or callback to produce a string error message. If a callback is used, it is passed the unloaded entity as the only argument.
Name
Type
Required
Default
Description
No arguments
``
Name
Type
Required
Default
Description
No arguments
``
Name
Type
Required
Default
Description
page
numeric
false
1
The page of results to return.
maxRows
numeric
false
25
The number of rows to return.
Name
Type
Required
Default
Description
page
numeric
false
1
The page of results to return.
maxRows
numeric
false
25
The number of rows to return.
Name
Type
Required
Default
Description
No arguments
``
Name
Type
Required
Default
Description
column
any
true
The name of the column with which to constrain the query. A closure can be passed to begin a nested where statement.
operator
any
true
The operator to use for the constraint (i.e. "=", "<", ">=", etc.). A value can be passed as the operator and the value left null as a shortcut for equals (e.g. where( "column", 1 ) == where( "column", "=", 1 ) ).
value
any
false
The value with which to constrain the column. An expression (builder.raw()) can be passed as well.
combinator
string
false
"and"
The boolean combinator for the clause (e.g. "and" or "or"). Default: "and"
Name
Type
Required
Default
Description
errorMessage
any
false
"No [#entityName()#] found with constraints [#serializeJSON( retrieveQuery().getBindings() )#]"
An optional string error message or callback to produce a string error message. If a callback is used, it is passed the unloaded entity as the only argument.
Name
Type
Required
Default
Description
attributes
struct
false
{}
A struct of attributes to restrict the query. If no entity is found the attributes are filled on the new entity returned.
newAttributes
struct
false
{}
A struct of attributes to fill on the new entity if no entity is found. These attributes are combined with attributes.
ignoreNonExistentAttributes
boolean
false
false
If true, does not throw an exception if an attribute does not exist. Instead, it skips the non-existent attribute.
Name
Type
Required
Default
Description
attributes
struct
false
{}
A struct of attributes to restrict the query. If no entity is found the attributes are filled on the new entity created.
newAttributes
struct
false
{}
A struct of attributes to fill on the created entity if no entity is found. These attributes are combined with attributes.
ignoreNonExistentAttributes
boolean
false
false
If true, does not throw an exception if an attribute does not exist. Instead, it skips the non-existent attribute.
Name
Type
Required
Default
Description
id
any
true
The id value to find.
Name
Type
Required
Default
Description
id
any
true
The id value to find.
errorMessage
any
false
"No [#entityName()#] found with id [#arguments.id#]"
An optional string error message or callback to produce a string error message. If a callback is used, it is passed the unloaded entity as the only argument.
Name
Type
Required
Default
Description
id
any
true
The id value to find.
attributes
struct
false
{}
A struct of attributes to fill on the new entity if no entity is found.
ignoreNonExistentAttributes
boolean
false
false
If true, does not throw an exception if an attribute does not exist. Instead, it skips the non-existent attribute.
Name
Type
Required
Default
Description
id
any
true
The id value to find.
attributes
struct
false
{}
A struct of attributes to use when creating the new entity if no entity is found.
ignoreNonExistentAttributes
boolean
false
false
If true, does not throw an exception if an attribute does not exist. Instead, it skips the non-existent attribute.
Name
type
required
default
description
name
string
wirebox name of the quick entity
Name
Type
Required
Default
Description
attributes
struct
false
{}
A struct of key / value pairs to fill in to the entity.
ignoreNonExistentAttributes
boolean
false
false
If true, does not throw an exception if an attribute does not exist. Instead, it skips the non-existent attribute.
Name
Type
Required
Default
Description
mementos
array
false
[]
An array of structs to hydrate into entities.
ignoreNonExistentAttributes
boolean
false
false
If true, does not throw an exception if an attribute does not exist. Instead, it skips the non-existent attribute.
Name
Type
Required
Default
Description
entities
array
false
[]
The array of entities returned by the query.
Name
Type
Required
Default
Description
ids
array
false
[]
An optional array of ids to add to the previously configured query. The ids will be added to a WHERE IN statement on the primary key columns.
Name
Type
Required
Default
Description
attributes
struct
false
{}
A struct of key / value pairs to update on the entity.
ignoreNonExistentAttributes
boolean
false
false
If true, does not throw an exception if an attribute does not exist. Instead, it skips the non-existent attribute.
Name
Type
Required
Default
Description
attributes
struct
false
{}
A struct of attributes to restrict the query. If no entity is found the attributes are filled on the new entity created.
newAttributes
struct
false
{}
A struct of attributes to update on the found entity or the new entity if no entity is found.
ignoreNonExistentAttributes
boolean
false
false
If true, does not throw an exception if an attribute does not exist. Instead, it skips the non-existent attribute.
Name
Type
Required
Default
Description
attributes
struct
false
{}
The attributes to update on the matching records.
force
boolean
false
false
If true, skips read-only entity and read-only attribute checks.
Name
Type
Required
Default
Description
No arguments
``
Name
Type
Required
Default
Description
No arguments
``
name | string |
| The name for the subselect. This will be available as an attribute. |
subselect | string OR QueryBuilder OR Function |
| Either a dot-delimited string representing a relationship chain ending with an attribute name, a QueryBuilder object, or a closure that configures a QueryBuilder object can be provided. If a closure is provided it will be passed a query object as its only parameter. The resulting query object will be used to computed the subselect. |
name | string |
| The attribute name to create. |
