-
Notifications
You must be signed in to change notification settings - Fork 0
Setting up Your Repositories
Scribe Repositories work like normal Repositories except they have convenience features managed by their config which enable automatically leveraging Scribe Entities, and building extendable queries based on the config.
Here are some of the features of Scribe Repositories:
Very often in projects, I will find that I or developers I am working with are having to write very similar queries again and again stored in methods in entity repositories. Then when something changes related to the entities retrieved by the queries all those existing lines of code need to change to accommodate what’s new.
Scribe offers extendable queries, where queries can extend other queries depending on the configuration context. This is handled via the extended configuration nature of Tempest Tools. Now you never need to repeat yourself, and never need to change your query configurations in more than 1 place to keep up to date with the changes in your project.
A Scribe Repository must extend "TempestTools\Scribe\Doctrine\RepositoryAbstract", or in the Skeleton application it can extend "App\Repositories\Repository".
Additionally, it must have a method to return a Scribe config for the Repository.
public function getTTConfig(): array
{
return [];
}
Ideally, it should have a placeholder for "default" context and "read" mode.
public function getTTConfig(): array
{
return [
'default'=>[
'read'=>[]
],
];
}
As with all Scribe configs, the top level keys of the config will refer to contexts, and the second level of the config will refer to modes.
Scribe Repositories configs are context sensitive. See here for more details.
Contextual,-Extendable-Configurations-and-More
Repository modes in the config relating to the whether the Repository is being accessed to "create", "read", "update" or "delete".
The only mode that truly needs to be managed in the Repository config is "read". The other modes are mostly managed by the config for Entities.
This block only goes in the "read" mode.
The query block contains an array that describes a SQL query that will be executed through Doctrine (generally written in DQL). These query blocks are generally used for the base query for index action requests.
Since the query blocks are extendable and context-sensitive, you can use these blocks to build queries that extend one another to prevent any query logic ever needing to be repeated.
The following sections describe the way to build a query inside of the query block of a config for a context.
It should be noted that in all the sections of the query the keys are arbitrary names. The purpose and usefulness of these names are described here:
An understanding of DQL is necessary for this section:
A select block lets you define select parts of the query.
The values here are blocks that will be passed in as DQL (or SQL) to the Doctrine query being built.
Here is a simple example of the skeleton:
'select'=>[
'artistsWithCustomAlias'=>'t',
'innerJoinTest'=>'a',
],
These sections set the "from" part of the query. You can include multiple "froms" if you like by setting an "append" value of "true". Each "from" is a different key value pair stored inside the "from" block.
If the "from" block is omitted, then a simple "from" block will be auto-generated with a table alias of "t"
Here are the different keys that go into a "from" block:
** className -- (string) Class name of the Entity associated with the base table from the query. ** alias -- (string), The alias to use in the "from". Tested in: testGeneralQueryBuilding. ** indexBy -- (string|null, Optional). indexBy functionality of Doctrine. ** append -- (boolean|null, Optional, Defaults to false) Whether or not to add as an additional "from", when you want more than 1 from in the query.
Here is a simple example
'from'=>[
'fromTest'=>[
'className'=>Artist::class,
'alias'=>'a',
'indexBy'=>null,
]
],
The where and having blocks use the same config syntax. They go in the where and having parts of the query respectively.
Condition blocks inside the where/having have a "type" and a "value"
** type -- ("and" | "or" | null>') If null then it's neither a 'and' or 'or' where clause, otherwise it can be set to 'and' or 'or' ** value -- (string|array) Either a string used in the where clause or an array.
The "value" key can have an array placed in it instead of simple DQL.
If an array of: ['expr'=>'', 'arguments'=>['<arguments, could be another xpr array>']] is used, then all parts will be parsed by the array helper, and corresponding xpr methods will be called with the specified arguments.
The array
Example of where clause without "expr" array:
// Get Docrtine expression builder:
$expr = new Expr();
...
'where'=>[
'simpleTest'=>[
'type'=>'and',
'value'=>$expr->eq(1, 1)
]
]
Example using an "expr" array:
'where'=>[
'exprArrayTest1'=>[
'value'=>[
'expr'=>'orX',
'arguments'=>[
[
'expr'=>'eq',
'arguments'=>[1,1]
],
[
'expr'=>'neq',
'arguments'=>[0,1]
],
]
]
]
]
Note that available expressions from the Doctrine expression build are:
['andX', 'orX', 'eq', 'neq', 'lt', 'lte', 'gt', 'gte', 'in', 'notIn', 'isNull', 'isNotNull', 'like', 'notLike', 'between' ]
Blocks inside the leftJoin and innerJoin block form DQL blocks to control (you guessed it) leftJoins and innerJoins.
Each block for joins may have the following:
** join -- (string) A join part of the query, such as
.. When using a queryType of sql use: .. IE: t.Albums ** alias -- (string) The alias the table will be joined as. Tested in: testGeneralQueryBuilding. Sql tested in testSqlQueryFunctionality ** conditionType -- ("ON" | "WITH" | null>) A condition type for the join such as: Expr\Join::WITH. ** condition -- (string | null, Defaults to "ON") A condition to join on such as x = x. ** indexBy -- (string | null, Optional). Doctrine indexBy functionality.Example block
'innerJoin'=>[
'innerJoinTest'=>[
'join'=>'t.albums',
'alias'=>'a',
'conditionType'=>Expr\Join::WITH,
'condition'=>$expr->eq(1, 1),
'indexBy'=>null,
]
],
The blocks in this block are used to build DQL orderBy statements for your query.
The keys in the orderBy blocks contain the following:
** sort -- (string|null) The field to be sorted by. ** order -- ("ASC"|"DESC"|null) The direction to order by. ASC or DESC.
Example orderBy block
'orderBy'=>[
'testOrderBy'=>[
'sort'=>'t.id',
'order'=>'DESC'
]
],
GroupBys only have a scalar value for each entry in the block. This value is a field too groupBy.
Here is an example of a groupBy block:
'groupBy'=>[
'groupByTest'=>'t.name'
],
Remeber that groupBy blocks generally should not be used unless you have aggregate columns in your select.
This block only goes in the "read" mode.
The settings block contains settings related to the query. It resides right inside the mode blocks of the config.
Here are the things you can specify in the settings block:
If "sql" is used then Doctrine DBAL query is used instead of an ORM query. Design your syntax accordingly.
"sql" type is permitted, but not recommended.
This block controls the cache settings for the query. Here are the keys you can place in it:
** queryCacheProfile -- (\Doctrine\DBAL\Cache\QueryCacheProfile|null, Optional, Defaults to universal settings for the application). See Doctrine docs for more information. Used only by SQL queries. ** useQueryCache -- (boolean|null, Optional, Defaults to true) Whether or not use query cache with the query. ** useResultCache -- (boolean|null, Optional, Defaults to false) Whether or not to use result cache with the query. ** timeToLive -- (int|null, Optional) The time to live of the cache. ** cacheId -- (string|null, Optional) A cache id to use for the result cache. ** queryCacheDrive -- (CacheProvider|null, Optional, Defaults to universal settings for the application) A cache driver to use other than the default ** resultCacheDriver -- (CacheProvider|null, Optional, Defaults to universal settings for the application) A cache driver to use other than the default
Here is an example of setting cache settings:
$arrayCache = new ArrayCache();
...
'cache'=>[
'useQueryCache'=>false,
'useResultCache'=>true,
'timeToLive'=>777,
'cacheId'=>'test_cache_id',
'queryCacheDrive' => $arrayCache,
'resultCacheDriver' => $arrayCache
],
Placeholders (also called query parameters) can be placed in the DQL of your query, this block can be used to set their values.
binding-parameters-to-your-query
Multiple blocks can go here with Descriptive Array Keys.
Here are the keys that go on each block:
** value -- (mixed) The value of the placeholder. ** type -- (PDO::PARAM_* | \Doctrine\DBAL\Types\Type::* constant | null, Optional) The type of the value. This is optional and while Doctrine supports it doesn't seem necessary or valuable.
Here is an example of setting a placeholder value
'placeholders'=>[
'placeholderTest'=>[
'value'=>'some stuff2',
]
],
This lets you control doctrines fetch join functionality used in Doctrine 2 pagination.
This block only goes in the "read" mode.
The permissions block can be used to set permissions for what kinds of requests can come from the front end.
The settings key can be applied in 6 places.
- At the level right below the mode
- inside the individual field block for each field, in the permissions for each part of the query (where, having, orderBy, groupBy, placeholders).
Settings have the universal Scribe features that are described here:
Here is an example block used for testing purposes with the settings shown at the highest level inside the mode.
'testTopLevelMutateAndClosure'=>[
'extends'=>[':default'],
'read'=>[
'permissions'=>[
'settings'=>[
'mutate'=>ArrayExpressionBuilder::closure(function () {
return [null, ['iAm'=>'a mutant']];
}),
'closure'=>ArrayExpressionBuilder::closure(function ($extra) {
return !$extra['settings']['iAm'] === 'a mutant';
})
]
]
]
],
Here is an example of the settings block for permissions used in all other places.
'testMutateAndClosure'=>[
'extends'=>[':default'],
'read'=>[
'permissions'=>[
'where'=>[
'fields'=>[
't.name'=>[
'settings'=>[
'mutate'=>$mutate,
'closure'=>$closure,
]
],
]
],
'having'=>[
'fields'=>[
't.name'=>[
'settings'=>[
'mutate'=>$mutate,
'closure'=>$closure,
]
],
]
],
'orderBy'=>[
'fields'=>[
't.name'=>[
'settings'=>[
'mutate'=>$mutate,
'closure'=>$closure,
]
],
]
],
'groupBy'=>[
'fields'=>[
't.name'=>[
'settings'=>[
'mutate'=>$mutate,
'closure'=>$closure,
]
]
]
],
'placeholders'=>[
'placeholderNames'=>[
'test'=>[
'settings'=>[
'mutate'=>$mutate,
'closure'=>$closure,
]
],
]
],
]
]
],
This goes just inside the permissions block.
allowed defaults to true. This block lets you turn on and off the access to the mode. In other words, if you put a 'allowed'=>false in your permissions block for "read", then read requests are not allowed in this config context.
This goes just inside the permissions block.
maxLimit defaults to 100. This is the maximum number of rows that a read query can return at a time. If more is requested with a higher limit and offset from the front end, an error will be thrown.
This goes just inside the permissions block.
fixedLimit defaults to null. If a fixedLimit is set then limit and offset requests from the front end must always be of a certain size. In other words with a fixedLimit of 10, then the limit must always be 10, and the offset must always be an increment of 10.
Use this to force the front end to always request consistent pages sizes.
The where and having blocks work the same way. One controls what requests the front end may make to filter the query using the where block, and the other controls the same for the having block.
Permisive permissioning is set here for the block. It also can be set inside the rules for a specific field.
This block allows you to set permissions for specific fields requested from the front end to be filtered.
It contains an array where the keys are field names with the table alias included (example: t.name).
The keys that can go on this block are as follows:
- settings (array|null) -- a settings block as described above.
- operators (array|null) -- an array of operators. The key of the array is the operator names ('andX', 'orX', 'eq', 'neq', 'lt', 'lte', 'gt', 'gte', 'in', 'notIn', 'isNull', 'isNotNull', 'like', 'notLike', 'between') and the value is a boolean of whether or not the front end may use that operator in a filter.
Example:
'testPermissions1'=>[
'extends'=>[':default'],
'read'=>[
'permissions'=>[
'where'=>[
'permissive'=>true,
'fields'=>[
't.name'=>[
'operators'=>[
'eq'=>false
]
]
]
]
]
]
],
orderBy works identically to the where / having block except instead of an "operators" block, it has an "directions" block. In the directions block the keys are either: "ASC" | "DESC" and a boolean value as to whether or not it's allowed.
Example:
'orderBy'=>[
'fields'=>[
't.name'=>[
'directions'=>[
'ASC'=>false
]
],
]
],
groupBy is a simpler block than the others. It's fields list only has a settings block and an "allowed" setting, which determines if the field that the block relates to is allowed to be grouped by on.
Example:
'groupBy'=>[
'fields'=>[
't.name'=>[
'allowed'=>false
],
]
],
placeholders sets permissions for what query placeholders the front end can set values too. It works just like the groupBy permissions block, with the key being the name of the placeholder.
Example
'placeholders'=>[
'placeholderNames'=>[
'test'=>[
'allowed'=>false
],
]
],
The blocks for these modes only have one option:
This boolean value will turn on and off the internal optimization feature of prePopulateEntities. This is on by default. It will analyze requests from the front end to find the ids of entities, and then it will load those entities from the database using the smallest number of queries possible.
Here an example of all the options that can go into a repository config:
// This is returned in the getTTConfig method of a repository.
$repoConfig = [
'<string>'=>[ // Context keys may be layered as deep as you like. They are part of the contextual config nature of Scribe. See documentation for more details.
'extends'=>['<string>'], // Optional. An array of string paths to extend from else where in the array. The values from array at the paths specified will be used as defaults for for the config.
'read'=>[ // Optional.
'query'=>[ // Optional.
'select'=>[ // Optional. A list of arbitrary key names with select strings to use in the query. Tested in: testBasicRead
'<string>'=>'<string|null>' //Tested in: testBasicRead
],
'from'=>[ // Optional. if not supplied it will be auto generated. A list of arbitrary key names and array keys and values to make a from part of the query. Tested in: testGeneralQueryBuilding. Sql tested in testSqlQueryFunctionality
'<string>'=>[ // Optional. Can be null to disable the block. Tested in: testGeneralQueryBuilding. Sql tested in testSqlQueryFunctionality
'className'=>'<string>', // Class name of the Entity associated with the base table from the query. Tested in: testGeneralQueryBuilding. Sql tested in testSqlQueryFunctionality
'alias'=>'<string>', // The alias to use in the from. Tested in: testGeneralQueryBuilding. Sql tested in testSqlQueryFunctionality
'indexBy'=>'<string|null>', // Optional. indexBy functionality of Doctrine. Tested in: testGeneralQueryBuilding. Sql tested in testSqlQueryFunctionality
'append'=>'<boolean|null>' // Defaults to false. Whether or not to ad as an additional from, when you want more than 1 from in the query. // Tested in: testGeneralQueryBuilding. Sql tested in testSqlQueryFunctionality
]
],
'where'=>[ // Optional. A list of arbitrary key names and strings, or arrays used to make where clauses. Tested in: testGeneralQueryBuilding
'<string>'=>[ // Can be null to disable the block. Tested in: testGeneralQueryBuilding
'type'=>'<"and" | "or" | null>', // If null then it's neither a 'and' or 'or' where clause, other wise it can be set to 'and' or 'or' Tested in: testGeneralQueryBuilding
'value'=>'<string|array>' // Either a string used in the where clause or an array. If an array of: ['expr'=>'<xpr name>', 'arguments'=>['<arguments, could be another xpr array>']] is used, then all parts will be parsed by the array helper, and corresponding xpr methods will be called with the specified arguments. This is true for all parts of the query //Tested in: testGeneralQueryBuilding
]
],
'having'=>[ // Optional. Works the same as the where section but applied to a having clause. Tested in: testGeneralQueryBuilding
'<string>'=>[ // Optional. Can be null to disable the block. Tested in: testGeneralQueryBuilding
'type'=>'<"and" | "or" | null>', //Tested in: testGeneralQueryBuilding
'value'=>'<string|array>' // Can be an array expression like with the where. Tested in: testGeneralQueryBuilding
]
],
'leftJoin'=>[ // Optional. A list of arbitrary key names and arrays with information about joins for the query. Tested in: testGeneralQueryBuilding. Sql tested in testSqlQueryFunctionality
'<string>'=>[ // Optional. Can be null to disable the block. Tested in: testGeneralQueryBuilding. Sql tested in testSqlQueryFunctionality
'join'=>'<string>', // A join part of the query, such as <table alias>.<relationship being joined to>. When using a queryType of sql use: <from alias>.<name of table to join too>. IE: t.Albums //Tested in: testGeneralQueryBuilding. Sql tested in testSqlQueryFunctionality
'alias'=>'<string>', // The alias the table will be joined as. Tested in: testGeneralQueryBuilding. Sql tested in testSqlQueryFunctionality
'conditionType'=>'<"ON" | "WITH" | null>', // Defaults to "ON". A condition type for the join such as: Expr\Join::WITH. Tested in: testGeneralQueryBuilding. Sql tested in testSqlQueryFunctionality
'condition'=>'<string | null>', // A condition to join on such as x = x. Tested in: testGeneralQueryBuilding. Sql tested in testSqlQueryFunctionality
'indexBy'=>'<string | null>', // Optional. Doctrine indexBy functionality. Tested in: testGeneralQueryBuilding. Sql tested in testSqlQueryFunctionality
]
],
'innerJoin'=>[ // Optional. Works the same as the leftJoin block but goes into innerJoin. Tested in: testGeneralQueryBuilding. Sql tested in testSqlQueryFunctionality
'<string>'=>[ // Optional. Can be null to disable the block. Tested in: testGeneralQueryBuilding. Sql tested in testSqlQueryFunctionality
'join'=>'<string>', // A join part of the query, such as <table alias>.<relationship being joined to>. When using a queryType of sql use: <from alias>.<name of table to join too>. IE: t.Albums //Tested in: testGeneralQueryBuilding. Sql tested in testSqlQueryFunctionality
'alias'=>'<string>', // The alias the table will be joined as. Tested in: testGeneralQueryBuilding. Sql tested in testSqlQueryFunctionality
'conditionType'=>'<"ON" | "WITH" | null>', // A condition type for the join such as: Expr\Join::WITH. Tested in: testGeneralQueryBuilding. Sql tested in testSqlQueryFunctionality
'condition'=>'<string | null>', // A condition to join on such as x = x. Tested in: testGeneralQueryBuilding. Sql tested in testSqlQueryFunctionality
'indexBy'=>'<string | null>', // Optional. Doctrine indexBy functionality. Tested in: testGeneralQueryBuilding. Sql tested in testSqlQueryFunctionality
]
],
'orderBy'=>[ // Optional. A list of arbitrary key names and arrays with information for building order bys. Tested in: testGeneralQueryBuilding
'<string>'=>[ // Optional. Can be null to disable the block. Tested in: testGeneralQueryBuilding
'sort'=>'<string|null>', // The field to be sorted by. Tested in: testGeneralQueryBuilding
'order'=>'<"ASC"|"DESC"|null>' // The direction to order by. ASC or DESC. Tested in: testGeneralQueryBuilding
]
],
'groupBy'=>[ // Optional. A list of arbitrary key names and a string to used to group by. Tested in: testGeneralQueryBuilding
'<string>'=>'<string|null>' // The field to group by. Tested in: testGeneralQueryBuilding
],
],
'settings'=>[ // Optional. Settings related to the query
'queryType'=>'<"dql" | "sql" | null>', // Defaults to dql, if sql is used then Doctrine DBAL query is used instead of an ORM query. Design your syntax accordingly. sql tested in testSqlQueryFunctionality
'cache'=>[ // Optional. Settings related to cache. Tested in: testGeneralQueryBuilding
'queryCacheProfile'=>'<\Doctrine\DBAL\Cache\QueryCacheProfile|null>',// Optional. See Doctrine docs for more information. Used only by SQL queries. Tested in testSqlQueryFunctionality
'useQueryCache'=>'<boolean|null>', // Defaults to true. Whether or not use query cache with the query. Can't be properly determined by a test case
'useResultCache'=>'<boolean|null>', // Defaults to false. Whether or not to use result cache with the query. Can't be properly determined by a test case
'timeToLive'=>'<int|null>', // Optional. The time to live of the cache. Tested in: testGeneralQueryBuilding
'cacheId'=>'<string|null>', // Optional. A cache id to use for the result cache. Tested in: testGeneralQueryBuilding
'tagSet'=>[ // Optional. Can be null to disable the block. Future release will include this functionality. This will allow result cache to be tagged with provided tags.
'<string>'=>[
'disjunction'=>'<boolean|null>',
'templates'=>[
'<string>'
]
]
]
],
'placeholders'=>[ // Optional. A list of arbitrary keys and place holders to inject into the query. Tested in: testGeneralQueryBuilding
'<string>'=>[ // Optional. Can be null to disable the block. Tested in: testGeneralQueryBuilding
'value'=>'<mixed>', //The value of the placeholder. Tested in: testGeneralQueryBuilding
'type'=>'<PDO::PARAM_* | \Doctrine\DBAL\Types\Type::* constant | null>' // Optional. The type of the value. This is optional and while Doctrine supports it it doesn't seem necessary or valuable. Tested in: testGeneralQueryBuilding
]
],
'fetchJoin'=>'<boolean|null>', // Defaults to true. Whether or not when paginating this query requires a fetch join // Tested in: testGeneralDataRetrieval
],
'permissions'=>[ // Optional. Permissions information related to the query.
'settings'=>[ // Optional. Can be null to disable the block.
'closure'=>'<closure|null>', // Optional. A closure to test if the current query can be allowed to proceed. Tested in testMutateAndClosure
'mutate'=>'<closure|null>', // Optional. A closure to mutate information about the current query before running it. Tested in testMutateAndClosure
],
'allowed'=>'<boolean|null>', // Default to true. Whether or not queries are allowed. Tested in testReadPermissions
'maxLimit'=>'<int|null>', // Defaults to 100. The maximum number of rows that can be returned at once. Tested in testGeneralDataRetrieval
'fixedLimit'=>'<int|null>', // Defaults to null. This can be used to force all returns to have the same number of rows. This is useful when it comes to caching to make sure the same types of pagination are requested every time. Tested in testFixedLimit
'where'=>[ // Optional. Can be null to disable the block. Permissions related to the where part of the query passed from the front end. Tested in testReadPermissions
'permissive'=>'<boolean|null>', // Defaults to true. Whether or not to use "permissive" permissions. Permissive true means that we assume that everything is allowed unless specified other wise, and false works in the opposite manner. Tested in testReadPermissions
'fields'=>[ // Optional. Can be null to disable the block. Permissions related to individual fields. Tested in testReadPermissions
'<string>'=>[ // Optional. Can be null to disable the block. The field name the permissions are related to. Tested in testReadPermissions
'permissive'=>'<boolean|null>', //Defaults to true. Whether or not to use "permissive" permissions. Permissive true means that we assume that everything is allowed unless specified other wise, and false works in the opposite manner.. Tested in testReadPermissions
'settings'=>[ // Optional.
'closure'=>'<closure|null>', // Optional. A closure that tests whether or not the query should be allowed to go forward. Tested in testMutateAndClosure
'mutate'=>'<closure|null>', // Optional. A closure to mutate information related to the field before it is used in the query. Tested in testMutateAndClosure
],
'operators'=>[ // Optional. Can be null to disable the block. A list of operators that are allowed or disallowed to be used in a filter from the front end. Tested in testReadPermissions
'<string>'=>'<boolean|null>' // Defaults to permissive setting. An operator name and whether or not it's allowed. Tested in testReadPermissions
]
]
]
],
'having'=>[ // Optional. Can be null to disable the block. Works the same as where permissions
'permissive'=>'<boolean|null>', // Defaults to true. Whether or not to use "permissive" permissions. Permissive true means that we assume that everything is allowed unless specified other wise, and false works in the opposite manner. Tested in testReadPermissions
'fields'=>[ // Optional. Can be null to disable the block. Permissions related to individual fields. Tested in testReadPermissions
'<string>'=>[ // Optional. Can be null to disable the block. The field name the permissions are related to. Tested in testReadPermissions
'permissive'=>'<boolean|null>', //Defaults to true. Whether or not to use "permissive" permissions. Permissive true means that we assume that everything is allowed unless specified other wise, and false works in the opposite manner.. Tested in testReadPermissions
'settings'=>[ // Optional.
'closure'=>'<closure|null>', // Optional. A closure that tests whether or not the query should be allowed to go forward. Tested in testMutateAndClosure
'mutate'=>'<closure|null>', // Optional. A closure to mutate information related to the field before it is used in the query. Tested in testMutateAndClosure
],
'operators'=>[ // Optional. Can be null to disable the block. A list of operators that are allowed or disallowed to be used in a filter from the front end. Tested in testReadPermissions
'<string>'=>'<boolean|null>' // Defaults to permissive setting. An operator name and whether or not it's allowed. Tested in testReadPermissions
]
]
]
],
'orderBy'=>[ // Optional. Can be null to disable the block. Permissions for order by requests from front end.
'permissive'=>'<boolean|null>', // Defaults to true. Whether or not to use "permissive" permissions. Permissive true means that we assume that everything is allowed unless specified other wise, and false works in the opposite manner. Tested in testReadPermissions2 and testReadPermissions3
'fields'=>[ // Optional. Can be null to disable the block.
'<string>'=>[ // Optional. Can be null to disable the block. The field name the permissions relate to. Tested in testReadPermissions2 and testReadPermissions3
'permissive'=>'<boolean|null>', // Defaults to true. Whether or not to use "permissive" permissions. Permissive true means that we assume that everything is allowed unless specified other wise, and false works in the opposite manner. Tested in testReadPermissions2 and testReadPermissions3
'settings'=>[ // Optional.
'closure'=>'<closure|null>', // Optional. A closure that tests whether or not the query should be allowed to go forward. Tested in testMutateAndClosure
'mutate'=>'<closure|null>', // Optional. A closure to mutate information related to the field before it is used in the query. Tested in testMutateAndClosure and testMutateUsed
],
'directions'=>[ // Optional. A list of directions that are allowed or not allowed. Tested in testReadPermissions2 and testReadPermissions3
'<"ASC" | "DESC">'=>'<boolean|null>' // Defaults to permissive setting. Whether or not the direction is allowed. Tested in testReadPermissions2 and testReadPermissions3
]
]
]
],
'groupBy'=>[ // Optional. Can be null to disable the block. Permissions for group by requests from front end. Tested in testReadPermissions2 and testReadPermissions3
'permissive'=>'<boolean|null>', // Defaults to true. Whether or not to use "permissive" permissions. Permissive true means that we assume that everything is allowed unless specified other wise, and false works in the opposite manner. Tested in testReadPermissions2 and testReadPermissions3
'fields'=>[ // Optional. Can be null to disable the block. Tested in testReadPermissions2 and testReadPermissions3
'<string>'=>[ // Optional. Can be null to disable the block. The field name the permissions relate to. Tested in testReadPermissions2 and testReadPermissions3
'allowed'=>'<boolean|null>', // Defaults to permissive setting. Whether or group by for this field is allowed. Tested in testReadPermissions2 and testReadPermissions3
'settings'=>[ // Optional.
'closure'=>'<closure|null>', // Optional. A closure that tests whether or not the query should be allowed to go forward. Tested in testMutateAndClosure
'mutate'=>'<closure|null>', // Optional. A closure to mutate information related to the field before it is used in the query. Tested in testMutateAndClosure and testMutateUsed
]
]
]
],
'placeholders'=>[ // Optional. Can be null to disable the block. Permissions for placeholders requests from front end.
'permissive'=>'<boolean|null>', // Defaults to true. Whether or not to use "permissive" permissions. Permissive true means that we assume that everything is allowed unless specified other wise, and false works in the opposite manner. Tested in testReadPermissions2 and testReadPermissions3
'placeholderNames'=>[ // Optional. Tested in testReadPermissions2 and testReadPermissions3
'<string>'=>[ // Optional. Can be null to disable the block. The name of the placeholder passed from the front end that permission relates too. Tested in testReadPermissions2 and testReadPermissions3
'allowed'=>'<boolean|null>', // Defaults to permissive setting. Whether or not use of this placeholder by the front end is allowed. Tested in testReadPermissions2 and testReadPermissions3
'settings'=>[ // Optional.
'closure'=>'<closure|null>', // Optional. A closure that tests whether or not the query should be allowed to go forward. Tested in testMutateAndClosure
'mutate'=>'<closure|null>', // Optional. A closure to mutate information related to the placeholder before it is used in the query. Tested in testMutateAndClosure and testMutateUsed
]
]
]
],
]
],
'create'=>[ // Optional. Can be null to disable the block.
'prePopulateEntities'=>'<boolean|null>' // Defaults to true, if true entities referenced in the params passed to CUD methods will be pre fetched using the minimum number of queries. // Tested in testPrePopulate
],
'update'=>[ // Optional. Can be null to disable the block.
'prePopulateEntities'=>'<boolean|null>' // Defaults to true, if true entities referenced in the params passed to CUD methods will be pre fetched using the minimum number of queries. // Tested in testPrePopulate
],
'delete'=>[ // Optional. Can be null to disable the block.
'prePopulateEntities'=>'<boolean|null>' // Defaults to true, if true entities referenced in the params passed to CUD methods will be pre fetched using the minimum number of queries. // Tested in testPrePopulate
]
]
];
Aside from the options you put in the config for a repository, there are also high level options that can be set on the "options" property of every repository.
These options can also be passed into the "create", "read", "update" and "delete" calls to reach repository.
Here is an example of setting the options property on a repo (default options shows.)
/**
* Default options for a repository
* @var array|NULL $options;
*/
protected $options = [
'paginate'=>true,
'hydrate'=>true,
'hydrationType'=>Query::HYDRATE_ARRAY,
'transaction'=>true,
'entitiesShareConfigs'=>true,
'flush'=>true,
'clearPrePopulatedEntitiesOnFlush'=>true
];
Option overrides can be set on the config for a controller as well, or passed directly to the methods "create", "read", "update" and "delete" of the repository if you are calling them directly.
Here is a break down of the options that can be set on a repository. Keep in mind that many of these have the same name as "settings" for a query.
Options override values stored in a "settings" block for a query.
Here is a list of the available options:
- paginate -- (boolean|null, Defaults to true) Whether or not paginate the results of a query.
- fetchJoin -- (boolean|null, Defaults to true) Whether or not to use a fetch join on a paginated query result.
- hydrate -- (boolean|null, Defaults to true) Whether or not to hydrate the results of a query. If false then the query object and info about the query is returned instead by the repo.
- hydrationType -- (Doctrine\ORM\Query::* constant|null, Defaults to: Query::HYDRATE_ARRAY) The hydration type for result sets.
- placeholders -- (Optional) Can be null to disable the block. Permissions for placeholders requests from front end.
- queryCacheProfile -- (\Doctrine\DBAL\Cache\QueryCacheProfile|null, Optional) See Doctrine docs for more details. Used only by SQL queries. Use a QueryCacheProfile object
- queryCacheDrive -- (\Doctrine\Common\Cache\Cache|null, Optional) Query cache driver, see Doctrine docs for more details.
- resultCacheDrive -- (\Doctrine\Common\Cache\Cache|null, Optional) Result cache driver, see Doctrine docs for more details.
- allowCache -- (boolean|null, Optional) Whether or not to allow cache.
- cacheId -- (string|null, Optional) An optional cache id to use for the result cache.
- useQueryCache -- (boolean|null, Defaults to true) Whether ot not to use query cache.
- useResultCache -- boolean|null, Defaults to false) Whether or not to use result cache.
- timeToLive -- (int|null, Optional) Time to live of the cache.
- tagSet -- (array|null, Optional) In a future version you can pass in cache tags to assign to the result cache. Not yet implemented
- transaction -- (boolean|null, Defaults to true) Whether ot not to process the database interactions as part of a transaction that will roll back on failure.
- entitiesShareConfigs -- (boolean|null, Defaults to true) If turned on like entities will share configs, mildly speeding up execution times.
- flush -- (boolean|null, Defaults to true) Whether or not to flush to the db at the end of call to Create, Read, Update, or Delete.
- batchMax -- (int|null, Optional) The maximum number of arrays that can be passed to a Create, Update or Delete method. Used for stopping requests that are to large.
- queryMaxParams -- (int|null, Optional) The maximum number of query params that can be passed to a Read method. Used for stopping requests that are to large.
- maxLimit -- (int|null, Defaults to 100) The maximum number of rows that can be returned at a time. Tested in testGeneralDataRetrieval
- prePopulateEntities -- (boolean|null, Defaults to true) if true entities referenced in the params passed to CUD methods will be pre fetched using the minimum number of queries.
- clearPrePopulatedEntitiesOnFlush -- (boolean|null, Defaults to true) whether or not when a flush occurred the pre populated entities should be cleared.
- fixedLimit -- (boolean|null, Defaults to false) This can be used to force all returns to have the same number of rows. This is useful when it comes to caching to make sure the same types pagination are requested every time.
Here is the list as the example appears in the code:
// Note: all options override query level options with the same names
$backendOptionsForRepo = [
'options'=>[
'paginate'=>'<boolean|null>', // Defaults to true. Whether or not paginate the results of a query. Tested in: testGeneralDataRetrieval
'fetchJoin'=>'<boolean|null>', // Defaults to true. Whether or not to use a fetch join on a paginated query result. Tested in: testGeneralDataRetrieval
'hydrate'=>'<boolean|null>', // Defaults to true. Whether or not to hydrate the results of a query. If false then the query object and info about the query is returned instead by the repo. Tested in: testGeneralDataRetrieval
'hydrationType'=>'<Doctrine\ORM\Query::* constant|null>', // Defaults to: Query::HYDRATE_ARRAY. The hydration type for result sets. Tested in: testGeneralDataRetrieval
'placeholders'=>[ // Optional. Can be null to disable the block. Permissions for placeholders requests from front end.
'<string>'=>[ // Optional. Can be null to disable the block. Keys of placeholders to inject into queries. Tested in: testGeneralDataRetrieval
'value'=>'<mixed>', // The value of the placeholder
'type'=>'<PDO::PARAM_* | \Doctrine\DBAL\Types\Type::* constant | null>' // Optional. type of the placeholders.
]
],
'queryCacheProfile'=>'<\Doctrine\DBAL\Cache\QueryCacheProfile|null>', // Optional. See Doctrine docs for more details. Used only by SQL queries. Use a QueryCacheProfile object
'queryCacheDrive'=>'<\Doctrine\Common\Cache\Cache|null>', // Optional. Query cache driver, see Doctrine docs for more details. Tested in: testGeneralQueryBuilding
'resultCacheDrive'=>'<\Doctrine\Common\Cache\Cache|null>', // Optional. Result cache driver, see Doctrine docs for more details. Tested in: testGeneralQueryBuilding
'allowCache'=>'<boolean|null>', // Optional. Whether or not to allow cache. Tested in: testGeneralQueryBuilding
'cacheId' => '<string|null>', // Optional. An optional cache id to use for the result cache. Tested in: testGeneralQueryBuilding
'useQueryCache' => '<boolean|null>', // Defaults to true. Whether ot not to use query cache. Tested in: testGeneralQueryBuilding
'useResultCache' => '<boolean|null>', // Defaults to false. Whether or not to use result cache. Tested in: testGeneralQueryBuilding
'timeToLive' => '<int|null>',// Optional. Time to live of the cache. Tested in: testGeneralQueryBuilding
'tagSet' => '<array|null>', // Optional. In a future version you can pass in cache tags to assign to the result cache. Not yet implemented
'transaction'=>'<boolean|null>', // Defaults to true. Whether ot not to process the database interactions as part of a transaction that will roll back on failure. Tested in testMultiAddAndChain
'entitiesShareConfigs'=>'<boolean|null>', // Defaults to true. If turned on like entities will share configs, mildly speeding up execution times. Tested in testMultiAddAndChain
'flush' => '<boolean|null>', // Defaults to true. Whether or not to flush to the db at the end of call to Create, Read, Update, or Delete. Tested in testMultiAddAndChain
'batchMax' => '<int|null>', // Optional. The maximum number of arrays that can be passed to a Create, Update or Delete method. Used for stopping requests that are to large. Tested in testMaxBatch
'queryMaxParams' => '<int|null>', // Optional. The maximum number of query params that can be passed to a Read method. Used for stopping requests that are to large. Tested in testGeneralDataRetrieval
'maxLimit' => '<int|null>', // Defaults to 100. The maximum number of rows that can be returned at a time. Tested in testGeneralDataRetrieval
'prePopulateEntities'=>'<boolean|null>', // Defaults to true, if true entities referenced in the params passed to CUD methods will be pre fetched using the minimum number of queries. // Tested in testPrePopulate
'clearPrePopulatedEntitiesOnFlush'=>'<boolean|null>', // Defaults to true. whether or not when a flush occurred the pre populated entities should be cleared. Tested in testPrePopulate
'fixedLimit'=>'<boolean|null>' // Defaults to false. This can be used to force all returns to have the same number of rows. This is useful when it comes to caching to make sure the same types pagination are requested every time. Tested in testFixedLimit
]
];