All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
5.1.0 - 2026-10-06
updateEntities()anddeleteByIds()now throw a 400HttpExceptionif the same ID is passed more than once, since this is likely a client error.
- When
validateEntity()is implemented,updateEntities()now throws a 404HttpExceptionif any of the rows can't be selected, rather than skipping them and returning a lower count. This matches the behavior of checking access withgetEntityById()before updating. A row returned more than once by the base query is now only validated once.
5.0.0 - 2026-10-05
updateEntities()method which replaces one or more rows, or updates them via a JSON Merge Patch when$partialis true.- Protected
processEntity()andinsertRows()methods, so an overriddenaddEntities()can access the processed rows without callingprocessValues()twice.processEntity()runsprocessValues(), converts the properties to a column/value row, runsvalidateEntity(), then runsprocessRow().insertRows()inserts the rows and returns their IDs. validateEntity()hook for validating the complete set of writable properties that will be saved. When updating, it is called for each row with the patch merged into the existing entity, along with the existing entity, and both include the ID property. The existing entity also contains the fields returned bygetEntityById(), such as computed properties. Writable properties which aren't selectable aren't in the existing entity, and are only in the merged entity if the patch sets them. If implemented, the ID property must be output, andupdateEntities()only updates rows that can be selected.
addEntities()no longer ignores anidproperty in the posted entities. IfgetMap()includes the ID property, the posted value is now inserted.Propproperties withoutput: falseare no longer selected unless another selected property depends on them, and requesting one in$fieldsnow throws a "not a valid field" exception. They can still be used for filtering and sorting. Settingoutput: falseon a writable property (one ingetMap()) now throws an exception.
afterInsert()hook. OverrideaddEntities()instead, usingprocessEntity()andinsertRows().isDefaultPropoption. All output properties are now selected unless a subset of fields is requested, and properties which shouldn't be output can setoutput: falseinstead. Since this changes the position of the following parameters, anyProparguments afternullGroupmust now be passed by name.updateById()andpatchByIds()methods. UseupdateEntities()instead.- Support for setting the ID of an existing row in
processValues()to skip inserting it. The ID is now treated like any other property, so a new row is inserted. To skip inserting rows, overrideaddEntities()instead.
4.2.0 - 2026-09-29
- With SQL Server and PostgreSQL,
addEntities()now returns the IDs from the insert query itself, so they are correct when other connections insert into the same table at the same time. - With SQL Server,
addEntities()returned the wrong ID for a single entity when an insert trigger inserted into another table with an identity column. patchByIds()anddeleteByIds()no longer fail when passed more IDs than the database allows bound parameters for. The IDs are split into multiple queries, which are run in a transaction.- With SQL Server, the counts returned by
updateById(),patchByIds(), anddeleteByIds()no longer include rows changed by triggers.
- PeachySQL 7.1+ is now required, and SQL Server 2016+ when using SQL Server.
- When
addEntities()requires multiple insert queries, they're now run in a transaction, so if one of them fails, none of the entities are inserted. - With SQL Server, bulk inserts into a view with an
INSTEAD OF INSERTtrigger now fail, since the IDs of rows inserted by the trigger can't be returned. No ID is returned when inserting a single entity into these views. - When inserting a single entity, the route handler returns a null ID if no ID is returned by
addEntities(), rather than the posted ID, which isn't inserted.
4.1.0 - 2026-07-15
afterInsert()hook which runs after rows are inserted, before their IDs are returned. It receives the inserted rows and their IDs, enabling follow-up work that depends on a successful insert.
- PHP 8.2+ is now required.
4.0.0 - 2025-01-03
getMap()is no longer abstract and returns an empty array by default, so it is no longer necessary to implement for read-only APIs.- If the ID column is returned from
getMap(), it is now automatically writable without having to set awritableIdflag. getSelectMap()now returns an empty array by default (rather than thegetMap()value), so it is no longer necessary to implement this method just to prevent selecting write-only properties when usinggetSelectProps().
Important
When upgrading, remove readonly ID properties from getMap(), and implement
getSelectMap() if any writable property is not returned by getSelectProps().
- Unnecessary
getDefaultValues()method. Defaults can be set viaprocessValues()instead. writableIdbool property.
3.0.0 - 2024-10-29
- Official support for PostgreSQL.
- Moved to
DevTheoremnamespace. - Phaster now validates that property values are scalar or null when inserting and updating rows.
- PHP 8.1+ is now required.
- All previously deprecated methods.
2.9.0 - 2024-09-10
processValues()now allows setting the ID of an existing row on the returned object, in which case a new row will not be inserted, and the specified ID will be returned in the list of row IDs.
2.8.0 - 2023-12-22
countEntities()method and correspondingcount()route handler. This allows counting the rows that match a query/filter without selecting them.
2.7.0 - 2023-09-27
writableIdbool property to optionally make the ID column writable.
2.6.0 - 2023-08-01
outputbool parameter onPropconstructor.
colis now optional when constructingPropwith agetValuefunction.
- Error when a
Propdepends on a property declared in one of theget*Mapmethods.
2.5.0 - 2023-03-05
- Minor code cleanup and refactoring.
getDuplicateError()andgetConstraintError()methods. These tend to just result in unhelpful error messages which lack important details about why the conflict occurred. A better approach is to add custom checks and errors for conflicts that can occur during normal usage.- Unnecessary
QueryOptionsmethods in favor of readonly properties.
2.4.0 - 2022-11-06
getSelectProps()method as a preferred alternative togetPropMap()when using PHP 8+.
- Moved most internal methods to a separate class for improved code maintainability.
getPropMap()method. UsegetSelectProps()instead.
2.3.0 - 2021-12-15
getBaseSelect()method to support bound params in base select query.
propertiesToColumns()now optionally allows conversions with a partial column map. This makes it possible to generate secondary filters using a subset of properties.
2.2.2 - 2021-08-15
- Internal refactoring and static analysis improvements.
2.2.1 - 2021-02-22
- Specified additional types and enabled Psalm static analysis.
- PHP 7.4+ is now required.
2.2.0 Primordial Refinement - 2020-03-22
getOriginalFilter()method toQueryOptionsfor retrieving the unprocessed filter array.
2.1.0 Benevolent Mystique - 2019-08-05
processRow()method to alter a row directly before it is inserted or updated. Useful for setting columns that aren't in the property map.
- PUT and PATCH requests now return the number of affected rows, and no longer produce an error if no rows were affected (e.g. if the request didn't change the value of any property).
- Excluded additional test files from production bundle.
2.0.0 Pressurized Arrangement - 2019-03-22
$sortparameter togetEntitiesByIds().
- By default, results are now ordered by the ID field.
$fieldsis now the second parameter ofgetEntities()instead of the last.
- Previously deprecated
getBaseSelect(),getIdColumn(),getSelectId(), androwsToJson()methods.
1.2.2 Pasteurized Recognition - 2019-03-04
getById()route handler now respectsfieldsparameter and only selects the specified properties.
1.2.1 Reliant Progenitor - 2019-02-24
- Support for specifying dependent fields along with
getValue()function. Dependents of requested fields that weren't explicitly requested, or aren't default, will still be selected but not output.
- Properly check
nullGroupproperties nested multiple levels deep. For example, when selecting the fielda.b.c, ifais a nullable group it will now be checked and set to null as expected. Previously only the direct parent of a selected field was checked.
1.2.0 Emancipation Propagation - 2019-02-22
- Default and maximum limit can now be configured for each search route. If not configured, these are set to 25 and 1000, respectively.
getBaseQuery()method, which has an$optionsparameter that an instance ofQueryOptionsis passed to. This makes it easy to only select specified field columns, and optionally customize the query based on which fields are selected or particular filter/sort values.getPropMap()method, which allows merging additional property info withgetSelectMap(). For example, a type or value getter function can be specified to determine how the property is output.- Optional
fieldsparameter ongetEntityById(),getEntitiesByIds(), andgetEntities()methods. Takes an array of strings specifying which fields to select. If left empty all default properties will be selected.
getBaseSelect()- usegetBaseQuery()instead.rowsToJson()- mapped property information is now used to automatically output selected fields.getIdColumn()andgetSelectId()- set anidproperty ingetSelectMap()orgetPropMap()instead. If the select query uses a different ID column name than the table used for inserts/updates/deletes, override the table's ID column name by setting anidproperty ingetMap().
1.1.1 Maximal Limitation - 2019-01-16
- Error when requesting the maximum page size of 1000.
- Upgraded peachy-sql dependency to v6.0.
1.1.0 Ambiguous Identity - 2019-01-11
getSelectId()method to optionally override the column used to get entities by ID. Necessary when a joined table has a column with the same name as the ID column.- Return
offset,limit, andlastPageproperties from search route handler. This makes it easy for API clients to see if there are more results to request.
1.0.2 Optimal Fixture - 2017-05-16
- Methods for retrieving, patching, and deleting entities by IDs now return early if passed an empty IDs array.
1.0.1 Exacting Characteristic - 2017-03-14
RouteHandlernow ensures that search parameters have the correct type.
1.0.0 Cosmic Luminary - 2017-03-09
- Initial stable release