PHPackages                             xwero/idable-queries-core - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. xwero/idable-queries-core

ActiveLibrary[Utility & Helpers](/categories/utility)

xwero/idable-queries-core
=========================

base package for Idable queries libraries

0.3.0(5mo ago)0141mitPHPPHP >=8.4

Since Nov 21Pushed 5mo agoCompare

[ Source](https://github.com/xwero/idable-queries-core)[ Packagist](https://packagist.org/packages/xwero/idable-queries-core)[ RSS](/packages/xwero-idable-queries-core/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (7)Dependencies (1)Versions (8)Used By (1)

Idable queries: core package
============================

[](#idable-queries-core-package)

This package provides the base functions and types for the database specific packages.

The main part of this package functions are helpers to work with the `Identifier` instances.

Overview
--------

[](#overview)

Idable queries are a set of packages that are at the core a multi-database wrapper. While you can use it as a wrapper with the same functions and types per database, the libraries provide an abstraction for the database names and parameters. At the base of the abstraction is the `Identifier` interface. It is nothing more than a library specific name for enums.

```
enum Users implements Indentifier
{
   case Users; // It is recommended to use enun name for the table/collection/set/... to make the identifier more universal
   case Name;
}

```

A backed enum is recommended to separate database name from the enum name.

A SQL query, `SELECT name FROM users WHERE name = 'me';`, can now be written as `SELECT ~Users:Name FROM ~Users:Users WHERE ~Users:Name = :Users:Name;`. A Redis query like `HMSET users name "Hello" email "World"` can be written as `HMSET ~Users:Users ~Users:Name :Users:Name ~Users:Email :Users:Email`. And so on with other database types.

> **note:** The placeholders are case-insensitive, but for the best compilation path in PHP it is recommended to use capitals.

To make it easier to add multiple parameters an `CustomParameterIdentifier` attribute can be added to an `Identifier` instance. This signals to the parameter functions that the parameter value will use a transformer to replace a single placeholder.

```
#[CustomParameterIdentfier('Xwero\IdableQueriesRedis\setParameterTransformer')]
enum Set implements Identfier
{
   case Users;
}

```

Now the Redis query can be written as `HMSET ~Users:Users :Set:Users`. And depending on the values in the `IdableParameterCollection` instance the query will be changed. Each database package will have predefined transformer functions. Creating the `Identifier` instance is up to the implementers.

The libraries will have map functions that transform the result of the query in an array-like structure where the key is an `Identifier` instance. As an example the `SELECT ~Users:Name FROM ~Users:Users WHERE ~Users:Name = :Users:Name;` query result called with the `createMapFromFirstLevelResults` function will have the `$map[Users:Name]` value me. This prevents typos when using the results.

The libraries are build with utility in mind. That is why the main functionality is in the functions, rather than in objects. Use as much or as little as you like.

Functions
---------

[](#functions)

### addIdableParameters

[](#addidableparameters)

This is the more dangerous version of the `collectIdableParameters` function, as it adds the values to the query without preparation.

`addIdableParameters('SELECT * FROM ~Users:Users WHERE ~Users:Name = :Users:Name;', IdableParameterCollection::createWithItem(User::Name, 'me')) ` results in `SELECT * FROM ~Users:Users WHERE ~Users:Name = me`

Used by the database system packages.

### buildAliasMap

[](#buildaliasmap)

This function allows full control over the creation of a `Map` instance. The data needs to be an associate array.

used by `buildAliasMapCollection`

### buildAliasMapCollection

[](#buildaliasmapcollection)

Helper function to transform a two-dimensional data array into an array of `Map` instances.

### buildLevelMap

[](#buildlevelmap)

Helper function to create a `Map` instance from an associate array.

Used by `createMapFromFirstLevelResults` and `createMapFromSecondLevelResults`.

### collectIdableParameters

[](#collectidableparameters)

This function allows the application code to prepare the parameters before adding it to the query.

Used by `replaceParametersInQuery`.

### createMapFromFirstLevelResults

[](#createmapfromfirstlevelresults)

Function with extra checks on top of `buildLevelMap`.

> **note:** This is more robust function, and should be the one used in a function chain.

Used by the database system packages.

### createMapFromSecondLevelResults

[](#createmapfromsecondlevelresults)

When the query returns multiple items use this function to create a `MapCollection`.

Used by the database system packages.

### fillMapWithAliases

[](#fillmapwithaliases)

A helper method for `buildAliasMap` and `buildLevelMap` to add data to the `Map` based on the added aliases.

### getIdentifierFromStrings

[](#getidentifierfromstrings)

This function accepts the class and case as a string and insures the return is either `null` or an identifier.

It is possible to add a number to the case in the occasion the same identifier needs to be used more than once. As an example `WHERE ~Users:Name = :Users:Name1 AND ~Users:Name != :Users:Name2`

Used by `queryToPlaceholderCollection`.

### getIdentifierRegex

[](#getidentifierregex)

This function gets the default regex or a custom one from the `IDENTIFIER_REGEX` environment variable.

### getParameterRegex

[](#getparameterregex)

This function get the default regex or a custom one from the `PARAMETER_REGEX` environment variable.

> **note:** Both regexes should have a colon as divider between the class and the case.

### isIdableQuery

[](#isidablequery)

Check to verify if a query has placeholders that can be picked up by the idable regexes.

### queryStringFromIdentifier

[](#querystringfromidentifier)

Gets a backed enum value or a lower string basic enum name.

Used by `buildlevelmap` and `PlaceholderReplacementCollection`.

### queryToPlaceholderCollection

[](#querytoplaceholdercollection)

This function extracts the strings that match the identifier regex and makes identifiers from the strings.

An error is returned when placeholders are found but the collections is empty. the most likely cause is a wrong namespace. It is not possible to return an error when only one or a few namespaces are wrong. To prevent unexpected results it is best to use the namespaces argument when the functions provide it.

> **note:** The collection is sorted from largest string size to smallest string size of the placeholders. This is to prevent bad replacements.

Used by `addQueryParameters`, `collectQueryParameters`, `createMapFromFirstLevelResults`, `createMapFromSecondLevelResults` and `replaceIdentifiersInQuery`.

### replaceIdentifiersInQuery

[](#replaceidentifiersinquery)

Replaces the identifier placeholders from the query with the database names.

Used by the database packages.

### replaceParametersInQuery

[](#replaceparametersinquery)

Replaces the parameter placeholders where the data isn't matched by the query placeholders. `:Arr:Test` will become `(:Arr:Test_0,:Arr:Test_1)` when used in the PDO package. The number of placeholders is based on the data in the `IdableParameterCollection`.

A `$placeholderTransformer` closure can be added to make sure the placeholders don't contain characters the database doesn't recognize.

Returns a `DirtyQuery` instance or false when there are no query changes.

Used by the database packages.

### runChain

[](#runchain)

When using a PHP version under 8.5, this function can be used to have a similar experience than with the pipe operator.

```
$query = 'SELECT ~Users:Name, ~Users:Email FROM ~Users:Users WHERE ~Users:Id = :UsersId';
$namespaces = new BaseNamespaceCollection('Test\Identifiers');
$result = replaceIdentifiersInQuery($query, $namespaces)
  |> (fn($query) => replaceParametersInQuery($query, new IdableParameterCollection(Users::Id, 1), $namespaces))
  |> (fn($queryAndParameters) => someDatabaseFunction($queryAndParameters))
  |> (fn($data) => createMapFromSecondLevelResults($data, $query, namespaces: $namespaces))
  ;

// with runChain

$query = 'SELECT ~Users:Name, ~Users:Email FROM ~Users:Users WHERE ~Users:Id = :UsersId';
$namespaces = new BaseNamespaceCollection('Test\Identifiers');
$result = runChain(new Chain(
                fn() => replaceIdentifiersInQuery($query, $namespaces)
                fn($query) => replaceParametersInQuery($query, new IdableParameterCollection(Users::Id, 1), $namespaces),
                fn($queryAndParameters) => someDatabaseFunction($queryAndParameters),
                fn($data) => createMapFromSecondLevelResults($data, $query, namespaces: $namespaces)
              ));

```

Types
-----

[](#types)

Most of the collection types are added to make sure the content is of a certain type.

### Alias

[](#alias)

A data transfer object that holds the information to be used by the functions that use the `AliasCollection`.

### AliasCollection

[](#aliascollection)

It is used to match aliases in the `buildAliasMap`, `buildAliasesMapCollection`, `buildLevelMap`, `createMapFromFirstLevelResults` and `createMapFromSecondLevelResults` functions.

The constructor only accepts `Alias` instances.

It has the methods:

- createWithItem: a static convenience method for `new AliasCollection()->add()`.
- add: this method uses the `Alias` constructor arguments to create an instance. This method can return an `Error` or the instance.
- getAlias: finds the matching `Alias` instance by a string value.

It extends `BaseCollection`.

### BaseCollection

[](#basecollection)

Has a single array to contain the collection items. Can be used for collections with a single type.

It has the methods:

- getAll: returns array
- isEmpty: checks the array size

### Chain

[](#chain)

Used to add closures to the `runChain` function.

The constructor only accepts `Closure` values.

Extends `BaseCollection`.

### CustomParameterIdentifier

[](#customparameteridentifier)

The class attribute to add to an `identifier` to allow custom parameter transformations. Database specific packages have data transformer functions to add to the attribute.

### DirtyQuery

[](#dirtyquery)

A DTO that is instantiated in `replaceParametersInQuery` when a query needs parameter replacements.

### Error

[](#error)

The catch-all exception type to make it easier to let them pass through a function chain.

### ExecutablePair

[](#executablepair)

Exposes the changed query and the placeholders that match the changed query.

### IdableParameter

[](#idableparameter)

The name is chosen to differentiate between parameter placeholders that use `Identifier` cases, and the native language parameters. The latter are most of the time added as an array to the functions.

To allow query placeholders with a trailing number this class is created get the value by `Identifier` and number.7 An example is `new IdableParameter(Users::Name, 'me', 1)`.

### IdableParameterCollection

[](#idableparametercollection)

Used to add values to the parameter identifier placeholders in the query. `:Users:name` is replaced by me when executing the query with the collection instance, `IdableParameterCollection::createWithItem(Users::Name, 'me')`.

The constructor accepts `IdableParameter` instances.

It has the methods:

- createWithItem: a static convenience for `new IdableParameterCollection()->add()`
- add: this uses the same arguments as the `IdableParameter` constructor to create an instance, and add it to the collection
- findValueByIdentifierAndPlaceholder: used by the `addIdableParameters` and `collectIdableParameters` functions

Extends `BaseCollection`.

### Identifier

[](#identifier)

The interface all the enums must implement to be used as placeholders in the queries and keys in maps.

A backed enum is recommended because it provides the best configuration. When it is a basic enum the case name will be lowercased to replace the placeholders.

### JSONError

[](#jsonerror)

A convenience class were the message needs to added to create an `Error` instance with and instance of the `JSONException` as the exception.

### JSONException

[](#jsonexception)

The message you add to the exception is appended with the JSON error message from PHP.

### Map

[](#map)

Added to make the language more consistent.

### MapCollection

[](#mapcollection)

The constructor only allows `Map` instances.

It has the method:

- addMap: appends a `Map` instance to the collection.

Extends `BaseCollection`.

### NamespaceCollection

[](#namespacecollection)

It is used to make the identifier placeholders in the queries shorter.

The constructor only accepts `string` values.

Extends `BaseCollection`.

### PlaceHolder

[](#placeholder)

This class binds the placeholder with the identifier, and optionally the value.

The class required properties are `placeholder` and `identifier`. The `value` property is used for collecting the data that a function passes on. The `prefix` and `suffix` properties are used to manipulate the `placeholder` return.

It has the methods:

- getFullPlaceholder: which concatenates the `prefix`, `placeholder` and `suffix` property values.
- getCustomValue: when the ´identifier´ value has a `CustomParameterIdentifier` attribute, this method will execute the data transformer function

### PlaceHolderCollection

[](#placeholdercollection)

The constructor only accepts `PlaceHolder` instances.

It has the methods:

- createWithPlaceholderItem: a static convenience with for `new Placeholder()->add()`
- add: uses the same arguments as the `PlaceHolder` constructor to create an instance and add it to the collection.
- getPlaceholderReplacements: returns a flattened array in case the placeholders in the query need to be replaced.
- getPlaceholdersAsText: calls the `getFullPlaceholder` on every item of the collection to create a string.
- getPlaceholderValuePairs: returns a flattened array with the placeholders and matching values

Extends `BaseCollection`.

### QueryReturnConfig

[](#queryreturnconfig)

The interface for database specific output configuration.

### Statement

[](#statement)

The interface to make the `Statement` classes consistent in the database specific packages.

Tips
----

[](#tips)

- Use the namespaces argument of the functions to prevent unexpected results because of typos or changed namespaces.

###  Health Score

36

—

LowBetter than 81% of packages

Maintenance76

Regular maintenance activity

Popularity6

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

7

Last Release

160d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/5f41aaa323f8e96ef3b41d829de30e74a0826d54b05ad1ddd355a50b0959740a?d=identicon)[xwero](/maintainers/xwero)

---

Top Contributors

[![xwero](https://avatars.githubusercontent.com/u/496309?v=4)](https://github.com/xwero "xwero (8 commits)")

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/xwero-idable-queries-core/health.svg)

```
[![Health](https://phpackages.com/badges/xwero-idable-queries-core/health.svg)](https://phpackages.com/packages/xwero-idable-queries-core)
```

###  Alternatives

[tzfrs/googlesitemapparser

Google Sitemap is a Sitemap standard that is supported by Ask.com, Google, YAHOO and MSN Search. This library can read in such Sitemaps and parse all urls from them.

143.3k](/packages/tzfrs-googlesitemapparser)[lrobert/gravatar

A library to make working with Gravatar in PHP easy.

101.4k](/packages/lrobert-gravatar)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)