A data mapper implementation for your persistence model in PHP.

Last update: Dec 30, 2022

Related tags

Database Atlas.Orm

Overview

Atlas.Orm

Atlas is a data mapper implementation for persistence models (not domain models).

As such, Atlas uses the term "record" to indicate that its objects are not domain objects. Use Atlas records directly for simple data source interactions at first. As a domain model grows within the application, use Atlas records to populate domain objects. (Note that an Atlas record is a "passive" record, not an active record. It is disconnected from the database.)

Documentation is at http://atlasphp.io.

Comments

How to use PHP-DI PSR 11 and Repository

php di config

 $containerBuilder->addDefinitions([
        Atlas::class =>  function (ContainerInterface $c) {
            $settings = $c->get('settings')['atlas']['pdo'];
            $atlasBuilder = new AtlasBuilder(...$settings);
            $atlasBuilder->setFactory(function ($class) use ($c) {
                if ($c->has($class)) {
                    return $c->get($class);
                }
            });

            return $atlasBuilder->newAtlas();
        },
    ]);

Repository

class TestRepository
{
    protected $mapper;

    public function __construct(TestThread $mapper)
    {
        $this->mapper = $mapper;    
    }
}

Error cannot be resolved: Entry "Atlas\Table\Table" cannot be resolved: the class is not instantiable

opened by izac1 1

Support for read-only MySQL generated columns
I am using a MYSQL generated column to represent a UUID (see this article for details).

This means there is one binary field I populate on insert with a computed default value using a Mapper Event ( issue 109 ). This never gets written to again after insert.

Then there is a generated column which returns the text UUID on every subsequent select. It cannot be written to.

CREATE TABLE `sp_users` ( ... `spu_uuid_bin` binary(16) DEFAULT NULL, `spu_uuid_text` varchar(36) GENERATED ALWAYS AS (insert(insert(insert(insert(hex(`spu_uuid_bin`),9,0,'-'),14,0,'-'),19,0,'-'),24,0,'-')) VIRTUAL,

With my normal UserMapper (from the skeleton generator), I get an error from MySQL on insert as the ORM tries to populate the read-only generated text column.

PDOException: SQLSTATE[HY000]: General error: 3105 The value specified for generated column 'spu_uuid_text' in table 'sp_users' is not allowed.

I followed issue 108 which describes a similar issue. So I can remove the field from the insert in beforeInsertRow, to cure the above error:

class UserTableEvents extends TableEvents{ // remove the generated field spu_uuid_text public function beforeInsertRow(Table $table, Row $row) : ?array { $copy = $row->getArrayCopy(); unset($copy['spu_uuid_text']); return $copy; }

However the solution there is for PosgreSQL which has the "returning" feature. I could not use the next two event examples to restore the field to fetch the generated value after insert. The PDOStatement fetch returns a "general error", either because the text field is missing or perhaps you cannot fetch the insert in MySQL.

I think there might be a solution here - with a modified version of the modifyInsertRow and afterInsertRow example, for MySQL?

As a workaround, I turned to my Repository, and thought I could just re-fetch the row there after the insert in my add() method. However the ORM Mapper parent class caches rows with an IdentityMap for the life of the Mapper class, and I cannot see a way to clear or defeat this cache. So the cached row still doesn't have the UUID text column (removed during insert) even when re-fetched. e.g.

public function add(SubjectUser $subject) { ...domain mapping... $this->atlas->insert($record); $record = $this->atlas->fetchRecord(UserRecord::class, $record->spu_id); return $record->spu_uuid_text; // field still empty from insert cache! }

So there could be a solution here if there is a way to clear the idenity map?

Finally, I ended up duplicating my entire UserMapper folder to create a second Mapper class to represent a "UserInsertMapper" and hacked out the UUID text field. This representation is used to do the insert, and then I use the normal "UserMapper" to re-fetch, which does perform an actual Select as it's a different mapper with a different IdentityMap, not populated. While this works, there's a lot of duplication between the mappers, the refetching is less performant, and it feels like a hack.

So finally, is there a more general option/method I'm missing, for supporting readonly MySQL fields?

thanks
opened by scipilot 0
Question: how to use raw insert values in ORM
The query system allows you to use SQL values during inserts, but I cannot see how to do this when using the ORM insert.

e.g. http://atlasphp.io/cassini/query/insert.html#1-4-4-1

$insert = $queryFactory->newInsert($connection); $insert->raw('bar', 'NOW()');

But I want to do:

$thread = $atlas->newRecord(Thread::CLASS, [ 'title' => 'New Thread Title', ]); // perhaps? $thread->raw('bar', 'NOW()'); // or? $thread->set(['bar', $atlas->raw("NOW()")]); $atlas->insert($thread);

I had a look at the source, but wasn't sure if it was possible this way.

Can it be added to the mapper definition?

Do I have to use Events and modify the row? (requires two queries)

(I know I can add it into the MySQL 8 defaults, but I'm still on 5. something. And I know I could use an SQL trigger.)

thanks
opened by scipilot 3

Postgres: problem when using uuid type field

@pmjones / @froschdesign --

We are looking to use Atlas ORM in our web app. This ORM seems amazing to work, with easy setup and logic 😄

In our web app, we use postgres as DBMS, with UUID columns as primary key.

CREATE TABLE user
(
    uuid uuid NOT NULL DEFAULT uuid_generate_v1(),
    login character varying(60)
    password character varying(60)
    email character varying(100)
    name character varying(255)
    status integer DEFAULT 0,

    CONSTRAINT user_pkey PRIMARY KEY (uuid),
    CONSTRAINT "email_UNIQUE" UNIQUE (email),
    CONSTRAINT "login_UNIQUE" UNIQUE (login),

    CONSTRAINT user_status_check CHECK (status >= 0)
)

In theory, when a new record is added, UUID column should be omitted. So postgres will generate a new uuid for the record.

But instead this error appears:

SQLSTATE[23502]: Not null violation: 7 ERROR:  null value in column "uuid" violates not-null constraint
D

We are using the following code (based on docs):

        // $datasource is an instance of Atlas

        $record = $dataSource->newRecord(User::class, [
            'login' => 'admin',
            'password' => password_hash($password, PASSWORD_DEFAULT),
            'email' => '[email protected]',
            'name' => 'Test Name',
            'status' => 1
        ]);

        $dataSource->insert($record);

It seems Atlas generate a SQL insert statement, sending NULL to UUID column. Looking at documentation, we didn't find a way to avoid it.

We looked in Atlas class core files and we found this

// Atlas\Table
// [...]
public function insertRowPrepare(Row $row) : Insert
    {
        $copy = $this->tableEvents->beforeInsertRow($this, $row);
        if ($copy === null) {
            $copy = $row->getArrayCopy();
        }

        $insert = $this->insert();
        $autoinc = static::AUTOINC_COLUMN;
        if ($autoinc !== null && ! isset($copy[$autoinc])) {
            unset($copy[$autoinc]);
        }
        $insert->columns($copy);

        $this->tableEvents->modifyInsertRow($this, $row, $insert);
        return $insert;
    }
// [...]

it seems when field is marked as Auto Increment, the column is omitted from insert. But that is not our case, since we use UUID 🤔

My questions are:

is this the default design of Altas ORM, only working with auto increment primary keys? Is there nothing we can do about for uuid field type?
can we use beforeInsertRow() method from TableEvents to omit uuid column from insert?

PS: We already consolidated our database model, we can't switch to IDs at this stage.

opened by juliovedovatto 3

Wrong parameters for PDOException?
Was trying to get the following:

PDOException (23000) SQLSTATE[23000]: Integrity constraint violation...

But I eneded up with:

Wrong parameters for PDOException([string $message [, long $code [, Throwable $previous = NULL]]])

because: https://github.com/atlasphp/Atlas.Orm/blob/d3d6bdbd53256b155967da9c28178729abdbff8f/src/Transaction/AutoTransact.php#L37

I think casting the code to an int resolves the issue, but I havent inspected enough to know if thats the correct solution:

throw new $c($e->getMessage(), (int) $e->getCode(), $e);
opened by jakejohns 1
Throw current exception instead of recreate them
Hello,

In case of some exceptions, order of parameters is not the same as Exception.

Error: Wrong parameters for PDOException([string $message [, long $code [, Throwable $previous = NULL]]])

So throw the current exception instead of recreate them is preferable.

Ronan
opened by ElGigi 5

Releases(3.1.1)

3.1.1(May 30, 2021)

Hygiene release.
Source code(tar.gz)
Source code(zip)
2.8.0(Jan 30, 2020)

This release backports a feature from the 3.x series, such that when the TableEvents::beforeInsert() or TableEvents::beforeUpdate() methods return an array, that array is used for the insert or update. This allows finer control over, among other things, the logic that determines differences from the initial Row data.

Expanded testing to include PHP 7.2 and 7.3.
Source code(tar.gz)
Source code(zip)
2.7.0(Mar 10, 2019)

This release adds support for 'manual' transactions outside a unit of work, via Atlas::beginTransaction(), commit(), and rollBack() methods.

Also, Row::isEquivalent() now compares booleans as integers, so that a change from 1 => true or 0 => false (and vice versa) is no longer considered a difference. This should help reduce "Expected 1 row affected, actual 0" errors with some databases (notably MySQL).
Source code(tar.gz)
Source code(zip)
2.6.0(Sep 17, 2018)

This release introduces an AtlasBuilder similar to the one in the 3.x series, thereby allowing you to lazy-load mappers instead of having to register them in advance. Using AtlasBuilder is now preferred over AtlasContainer, though of course the latter continues to work as before. Documentation and tests have been updated accordingly.
Source code(tar.gz)
Source code(zip)
2.5.0(Aug 15, 2018)

This release exposes underlying profiler functionality in Aura.Sql ConnectionLocator via two new methods: Atlas::setProfiling() and Atlas::getProfiles().

It also incorporates two performance enhancements: one to AbstractMapper::newRelated() via a prototype object for relateds, and one to AbstractTable::newRow() via array_intersect_key() comparison.
Source code(tar.gz)
Source code(zip)
3.1.0(Aug 8, 2018)
Added methods Atlas::logQueries() and Atlas::getQueries(), to expose the query logging functionality of the ConnectionLocator.

Updated docs and tests

Source code(tar.gz)
Source code(zip)
3.0.0(Jul 10, 2018)
Added methods Atlas::newRecords() and Atlas::persistRecords()

For consistency with other methods, Atlas::persistRecordSet() now returns void, and no longer detaches deleted records

Updated docs

Source code(tar.gz)
Source code(zip)
2.4.0(Jun 4, 2018)

This release fixes a bug where MapperEvents::modifySelect() was not being honored by various AbstractMapper::fetch() methods. Two new off-interface methods, AbstractTable::selectRow() and selectRows(), are introduced as a result.
Source code(tar.gz)
Source code(zip)
3.0.0-beta1(May 8, 2018)

This release provides a PHPStorm metadata resource to aid in IDE autocompletion of return typehints, found at resources/phpstorm.meta.php. Copy it to the root of your project as .phpstorm.meta.php, or add it to your root-level .phpstorm.meta.php/ directory as atlas.meta.php.

Also, the documentation and tests for this package have been updated to honor changes to the underlying Mapper and Table packages. In particular, the Mapper classes no longer use a Mapper suffix.
Source code(tar.gz)
Source code(zip)
2.3.0(May 6, 2018)

This release adds one "off-interface" method, AbstractTable::getIdentityMap(), to support retrieval of initial values on rows.

It also fixes a bug where a relationship definition could use the same name more than once, silently overwriting the previous definition.

Finally, it includes updated documentation and tests.
Source code(tar.gz)
Source code(zip)
3.0.0-alpha1(Apr 19, 2018)

Initial release of the 3.x series.
Source code(tar.gz)
Source code(zip)
2.2.0(Mar 19, 2018)

This release adds two "off-interface" events, TableEvents::modifySelect() and MapperEvents::modifySelect(), to allow modification of the TableSelect and MapperSelect query objects.

These events are added only to the implementation classes, and not the interfaces, to make the functionality available without introducing a BC break. A future major revision may incorporate them into the relevant interfaces.

It also fixes the bug noted at https://github.com/atlasphp/Atlas.Orm/issues/86 where existing connections are not updated to the current transaction state.
Source code(tar.gz)
Source code(zip)
2.1.0(Feb 6, 2018)
This release adds support for many-to-one relationships by reference (aka "polymorphic association") in addition to some convenience and informational methods.

Documentation and code hygiene fixes

Add method Mapper\Related::getFields()

Add method Mapper\RecordSet::removeAll()

Add method Mapper\RecordSet::markForDeletion()

Add method Relationship\Relationships::manyToOneByReference()

Add method Mapper\AbstractMapper::manyToOneByReference()

Source code(tar.gz)
Source code(zip)
2.0.0(Oct 17, 2017)

Documentation changes and updates.
Source code(tar.gz)
Source code(zip)
2.0.0-beta1(Oct 3, 2017)
MOTIVATION:

In 1.x, executing a Transaction::persist() will not work properly when the relationships are mapped across connections that are not the same as the main record. This is because the Transaction begins on the main record connection, but does not have access to the connections for related records, and so cannot track them. The only way to fix this is to introduce a BC break on the Table and Transaction classes, both their constructors and their internal operations.

As long as BC breaks are on the table, this creates the opportunity to make other changes, though with an eye to minimizing those changes to reduce the hassle of moving from 1.x to 2.x.

UPGRADE NOTES FROM 1.x:

This package now requires PHP 7.1 or later, and PHPUnit 6.x for development. Non-strict typehints have been added throughout, except in cases where they might break classes generated from 1.x.

You should not need to modify any classes generated from 1.x; however, if you have overridden class methods in custom classes, you may need to modify that code to add typehints.

This package continues to use Aura.Sql and Aura.SqlQuery 2.x; you should not need to change any queries.

You should not need to change any calls to AtlasContainer for setup.

The following methods now return null (instead of false) when they fail. You may need to change any logic checking for a strict false return value; checking for a loosely false-ish value will continue to work.

AbstractMapper::fetchRecord()

AbstractMapper::fetchRecordBy()

AbstractTable::fetchRow()

Atlas::fetchRecord()

Atlas::fetchRecordBy()

IdentityMap::getRow()

MapperInterface::fetchRecord()

MapperInterface::fetchRecordBy()

MapperSelect::fetchRecord()

RecordSet::getOneBy()

RecordSet::removeOneBy()

RecordSetInterface::getOneBy()

RecordSetInterface::removeOneBy()

Table::updateRowPerform()

TableInterface::fetchRow()

TableSelect::fetchOne()

TableSelect::fetchRow()

(N.b.: Values for a single related record are still false, not null. That is, null still indicates "there was no attempt to fetch a related record," while false still indicates "there was an attempt to fetch a related record, but it did not exist.")

The following methods will now always return a RecordSetInterface, even when no records are found. (Previously, they would return an empty array when no records were found.) To check for "no records found", call isEmpty() on the returned RecordSetInterface.

AbstractMapper::fetchRecordSet()

AbstractMapper::fetchRecordSetBy()

MapperInterface::fetchRecordSet()

MapperInterface::fetchRecordSetBy()

MapperSelect::fetchRecordSet()

MapperSelect::fetchRecordSetBy()

OTHER CHANGES FROM 1.x:

Added Atlas\Orm\Table\ConnectionManager to manage connections at a table- specific level.

Manages simultaneous transactions over multiple connections.

Allows setting of table-specific "read" and "write" connections.

Allows on-the-fly replacement of "read" connections with "write" connections while writing (useful for synchronizing reads with writes while in a transaction) or always (useful for GET-after-POST situations).

If the ConnectionManager starts a transaction on one connection (whether read or write) then it will start a tranasaction on all connections as they are retrieved.

AbstractTable now uses the ConnectionManager instead of Aura.Sql ConnectionLocator, and does not retain (memoize) the connection objects. It retrieves them from the ConnectionManager each time they are needed; this helps maintain transaction state across multiple connections.

Modified Transaction class to use the ConnectionManager, instead of tracking write connections on its own. This makes sure AbstractMapper::persist() will work properly with different related connections inside a transaction.

The ManyToMany relationship now honors the order of the returned rows.

Updated docs and tests.

Source code(tar.gz)
Source code(zip)
1.3.2(Oct 2, 2017)
ManyToMany relationship now honors the query order of returned rows. (#76)

Fixes to docs and imports

Source code(tar.gz)
Source code(zip)
1.3.1(Aug 23, 2017)
AbstractTable::insertRowPerform() now uses the correct sequence name for the last insert ID on Postgres. (#71)

Substantial documentation updates and additions; thanks, @jelofson!

Source code(tar.gz)
Source code(zip)
1.3.0(Jun 29, 2017)
Changed Mapper::insert() and Mapper::update() to auto-set foreign key values on relateds

Added Mapper::persist() to insert/update/delete a Record and all its relateds. Also available via added Atlas::persist() and Transaction::persist() methods.

In AbstractRelationship::fetchForeignRecords() no longer issues an empty IN() query if there are no native records to match against. (Fixes #58.)

AtlasContainer constructor now accepts a ConnectionLocator as an alternative to a PDO object or PDO connection params. (Cf. #63 and #64.)

Updated readme, docs and tests.

Source code(tar.gz)
Source code(zip)
1.2.1(May 23, 2017)
Docs updates and fixes

Fixed error when using PDO in AtlasContainer constructor (#53)

Source code(tar.gz)
Source code(zip)
1.2.0(Apr 18, 2017)
Added where() functionality for relationships.

Source code(tar.gz)
Source code(zip)
1.1.0(Apr 10, 2017)
Added ignoreCase() option on relationships.

Source code(tar.gz)
Source code(zip)
1.0.0(Apr 6, 2017)
Add TableSelect::fetchCount() to return a row-count, without limit/offset, on a reused query object.

Add RecordSet::appendNew(), getOneBy(), getAllBy(), removeOneBy(), and removeAllBy()

Rename AbstractTable::insert(), update(), delete() to insertRow(), updateRow(), deleteRow() ...

... then rename AbstractTable::newInsert() to insert() , newUpdate() to update(), newDelete() to delete(); this is in line with the pre-existing select() method returning a new select object.

Row, Record, and RecordSet now implement JsonSerializable

Expand MapperEventsInterface to allow modifyInsert() etc.

Relax set() on Row, Record, and Related, to allow for non-fields in the setting array

Mapper::newRecord() now allows Related values in addition to Row values

Row::modify() now restricts to scalar or null

Related::modify() now restricts to null, false, [], Record, and RecordSet

Added MapperSelect::joinWith(), leftJoinWith(), innerJoinWith() to allow joins to relateds, without fetching

In AtlasContainer::__construct() et al, allow for pre-existing ExtendedPdo and PDO connections

Add TableEvents::modifySelectedRow() to allow changes to rows coming from the database

MapperSelect::with() now throws an exception when you use a non-existent related name

AbstractMapper::(one|many)To(One|Many)() no longer allows related names that conflict with column names

MapperSelect::with() now allows for nested arrays (in addition to anonymous functions)

Documentation and testing updates.

Source code(tar.gz)
Source code(zip)
1.0.0-alpha1(Oct 13, 2016)

First alpha release.
Source code(tar.gz)
Source code(zip)
0.3.0-alpha(Feb 18, 2016)
Major backwards-compatibility breaks. I expect further BC breaks, but for them to be much less dramatic; functionality is starting to stabilize. Among the major breaks:

Collapse Gateway into AbstractTable

Composite key support: primary keys as well as foreign keys

Removed custom getter/setter/copier interceptor methods in Row

No more custom Row objects

AbstractTable::getAutoinc() now returns a col name, not a bool

Removed Relationship::setNative() and setForeign(), replaced with on(); this is to better support composite key mappings.

AbstractTable::delete() now expects to delete a row, instead of allowing for the row to not exist

Rename Plugin to Events, split across Table and Mapper

Source code(tar.gz)
Source code(zip)
0.2.0-alpha(Jan 8, 2016)

This release exposes more of the internals for type-specific overrides.

The Mapper class has been deconstructed to an earlier form, where the table data Gateway is a separate object. Likewise, the Row emitted by the Gateway can now be type-specific.

The Plugin class method signatures have been changed to take a Gateway and Row, instead of a Mapper and Record, in most cases.

If you have existing Table classes, they will continue to work, but I suggest you re-generate them with the new 0.2.0-alpha CLI tool, so that the primary key is represented by an array instead of a string. (Or, hand-edit your TypeTable::getPrimaryKey() methods to return an array instead of a string.) The next release of the ORM is expected to support composite keys, at which time a string-represented primary key may not be supported any more.
Source code(tar.gz)
Source code(zip)
0.1.0-alpha(Dec 29, 2015)

Initial release. Breaking changes are guaranteed, but it's stable enough to play with.
Source code(tar.gz)
Source code(zip)

Owner

GitHub http://atlasphp.io

Articulate - An alternative ORM for Laravel, making use of the data mapper pattern

Articulate Laravel: 8.* PHP: 8.* License: MIT Author: Ollie Read Author Homepage: https://ollie.codes Articulate is an alternative ORM for Laravel bas

4 Jan 4, 2022

[READ-ONLY] A flexible, lightweight and powerful Object-Relational Mapper for PHP, implemented using the DataMapper pattern. This repo is a split of the main code that can be found in https://github.com/cakephp/cakephp

CakePHP ORM The CakePHP ORM provides a powerful and flexible way to work with relational databases. Using a datamapper pattern the ORM allows you to m