README

ASLinkORM是一个轻量级的对象关系映射（ORM）库，允许您使用面向对象模型与数据库进行交互。此库旨在简化PHP应用程序中数据库记录和关系的管理过程。

安装

使用Composer

Composer依赖

composer require alphasoft-fr/aslink-orm

要求

• PHP版本8.2

介绍

ASLinkORM - 以简单和灵活的方式管理您的SQL数据。

ASLinkORM是一个面向对象关系映射（ORM）解决方案，旨在解决现代项目中出现的一个特定需求。在很多情况下，项目继承了没有使用ORM创建的现有数据库。然而，随着像Symfony这样的框架的兴起，它们倡导使用Doctrine ORM，将这些现有数据库集成到Symfony项目中时出现了挑战。

使用Doctrine ORM处理这些数据库带来了困难。它涉及手动创建大量实体，将列映射到实体属性，管理数据库迁移等劳动密集型任务。此外，这种方法在数据管理上施加了约束并限制了灵活性。

为了应对这些挑战，我们构思了ASLinkORM，这是一个定制的ORM，旨在简化SQL数据管理并提供显著的灵活性。目标是创建一个ORM，它可以无缝地集成到基于Symfony或类似框架的现有项目中，而无需重新创建实体或复杂的迁移。

ASLinkORM以其易用性和与现有数据库的无缝集成能力而脱颖而出，无需施加沉重的配置开销。它提供了一种更流畅的数据映射方法，使开发者能够直观地管理实体和表之间的关系。此外，它提供了一个灵活的数据库迁移替代方案，使开发者可以控制这些过程。

在本指南中，我们将深入了解ASLinkORM的复杂功能，展示如何将其集成到您的项目中，以及它如何简化SQL数据管理，同时提供必要的适应性以满足您的特定需求。

ASLinkORM利用Doctrine DBAL的强大功能进行高效的SQL数据管理。

入门

要开始使用ASLinkORM，您需要遵循以下步骤

1. 初始化DoctrineManager：在应用程序的入口点，使用您的数据库配置初始化DoctrineManager。确保根据您的数据库设置调整配置。

use AlphaSoft\AsLinkOrm\EntityManager;

$config = [
     'url' => 'mysql://username:password@localhost/db_name',
     // ... other options
 ];

 $manager = new EntityManager($config);

1. 创建仓库：通过扩展Repository基本类创建用于您的模型的仓库类。定义表名、模型名和可选字段。

use AlphaSoft\AsLinkOrm\Repository\Repository;

class UserRepository extends Repository
{
    public function getTableName(): string
    {
        return 'user'; // Name of the associated table
    }
    
    public function getModelName(): string
    {
        return User::class; // Fully qualified name of the model class
    }
    
    // Additional methods for custom queries
}

1. 创建模型：通过扩展HasEntity基本类创建模型类。定义关系和您需要的任何自定义方法。

use AlphaSoft\AsLinkOrm\Relation\HasEntity;

class User extends HasEntity 
{
    static protected function columnsMapping(): array
    {
        return [
            new \AlphaSoft\AsLinkOrm\Mapping\PrimaryKeyColumn('id'),
            new \AlphaSoft\AsLinkOrm\Mapping\Column('firstname'),
            new \AlphaSoft\AsLinkOrm\Mapping\Column('lastname'),
            new \AlphaSoft\AsLinkOrm\Mapping\Column('email'),
            new \AlphaSoft\AsLinkOrm\Mapping\Column('password'),
            new \AlphaSoft\AsLinkOrm\Mapping\Column('isActive', false, 'is_active'),
        ];
    }

    static public function getRepositoryName(): string
    {
        return UserRepository::class;
    }

    public function getPosts(): \SplObjectStorage
    {
        return $this->hasMany(Post::class, ['user_id' => $this->getPrimaryKeyValue()]);
    }
}

访问仓库

在ASLinkORM中，仓库充当访问和操作底层数据库表数据的网关。要访问仓库，您可以使用您已设置的DoctrineManager实例。以下是如何使用管理器检索仓库的示例

use Your\Namespace\DoctrineManager;
use Your\Namespace\Repository\UserRepository;

// Assuming you have a configured DoctrineManager instance
$manager = new DoctrineManager(/* configuration options */);

// Retrieving a UserRepository instance
$userRepository = $manager->getRepository(UserRepository::class);

在此示例中，您创建一个DoctrineManager实例，然后使用它来检索一个UserRepository实例。您可以将UserRepository替换为您定义的任何仓库类的名称。

基本操作

以下是一些您可以使用ASLinkORM执行的基本操作示例

插入记录

use Your\Namespace\User;

$user = new User([
    'firstname' => 'John',
    'lastname' => 'Doe',
    'email' => 'john@example.com',
    'isActive' => true,
]);

$userRepository->insert($user);

查找记录

$user = $userRepository->findOneBy(['id' => 1]);

更新记录

$user = $userRepository->findOneBy(['id' => 1]);

$user->set('firstname', 'UpdatedName');
$userRepository->update($user);

删除记录

$user = $userRepository->findOneBy(['id' => 1]);

$userRepository->delete($user);

从模型检索数据

在您的框架中，您可以使用各种方法从模型中检索数据。主要的方法是get方法，允许您通过指定名称来访问属性值。

$user = new User();
$user->set('firstname', 'John');
$firstname = $user->get('firstname'); // Retrieves 'John'

如果指定的属性在模型中不存在，则会抛出InvalidArgumentException异常。

使用getOrNull进行安全检索

为了安全地检索数据而不触发异常，您可以使用getOrNull方法，如果属性存在则返回其值，如果不存在则返回null。

$lastname = $user->getOrNull('lastname'); // Retrieves 'null'

特定类型检索

您还可以使用专用方法检索具有特定数据类型的属性值。这些方法提供类型检查，不允许在属性未定义或值类型错误时使用默认值。

• getString检索字符串值。

$lastname = $user->getString('lastname', 'Doe'); // Retrieves 'Doe' if 'lastname' exists and is a string

• getInt检索整数值。

$age = $user->getInt('age', 25); // Retrieves 25 if 'age' exists and is an integer

• getFloat检索浮点值。

$price = $product->getFloat('price', 0.0); // Retrieves 0.0 if 'price' exists and is a float

• getBool检索布尔值。

$isActive = $user->getBool('isActive', false); // Retrieves false if 'isActive' exists and is a boolean

• getArray检索数组。

$tags = $post->getArray('tags', []); // Retrieves an empty array if 'tags' exists and is an array

• getInstanceOf检索指定类的实例，如果存在且是指定类的实例，则返回null。

$profile = $user->getInstanceOf('profile', Profile::class); // Retrieves an instance of Profile or null if 'profile' exists and is an instance of Profile

• getDateTime检索DateTimeInterface实例，可选地指定解析格式。

$createdAt = $post->getDateTime('created_at', 'Y-m-d H:i:s'); // Retrieves a DateTimeInterface instance or null if 'created_at' exists and is convertible to a valid date

请注意，如果属性未定义或值类型错误，这些方法将抛出异常。如果您想允许默认值，可以使用带有默认值的先前示例，但在这些情况下它们不会抛出异常。

关系

ASLinkORM通过允许您定义和管理模型之间的关系来扩展其功能。通过扩展HasEntity类，您可以轻松建立允许您导航和交互相关数据的关联关系。

定义关系

HasEntity类提供两种方法，hasOne和hasMany，这些方法简化了关系管理。让我们通过示例来探讨这些方法

hasOne方法

hasOne方法在当前模型和另一个相关模型之间建立一对一关系。以下是如何使用它的示例

use AlphaSoft\AsLinkOrm\Entity\AsEntity;

class User extends AsEntity
{
    // ... (other code)
    
    public function getProfile(): ?Profile
    {
        return $this->hasOne(Profile::class, ['user_id' => $this->getPrimaryKeyValue()]);
    }
}

在这种情况下，getProfile方法设置了User模型和Profile模型之间的一对一关系。它返回与用户关联的单个Profile实例。

hasMany方法

hasMany方法在当前模型和另一个相关模型之间建立一对多关系。请考虑以下示例

use AlphaSoft\AsLinkOrm\Entity\AsEntity;

class User extends AsEntity
{
    // ... (other code)
    
    public function getPosts(): \SplObjectStorage
    {
        return $this->hasMany(Post::class, ['user_id' => $this->getPrimaryKeyValue()]);
    }
}

在此示例中，getPosts方法设置了User模型和Post模型之间的一对多关系。它返回一个包含与用户关联的所有帖子的SplObjectStorage。

导航关系

在定义关系后，您可以无缝地导航数据图。以下是如何利用建立的关系检索关联数据的示例

$user = $userRepository->findOneBy(['id' => 1]);

// Retrieve the user's profile
$profile = $user->getProfile();

// Retrieve all posts associated with the user
$posts = $user->getPosts();

foreach ($posts as $post) {
    // Access post attributes
    $title = $post->get('title');
    $content = $post->get('content');
    // ... (other operations)
}

通过利用hasOne和hasMany方法，您可以有效地检索和操作关联数据，使您的数据交互更加直观和有效。

定义列映射

ASLinkORM提供为模型定义列映射的能力，这为您提供了管理数据时的灵活性。

columnsMapping()

在columnsMapping()方法中，使用Column对象来定义模型属性如何对应数据库列。它允许您指定默认值和可选的数据库列名（如果与模型中的属性名称不同）。

use AlphaSoft\AsLinkOrm\Mapping\Column;

$column1 = new Column('firstname'); // Basic usage, no specific column name specified
$column2 = new Column('lastname', 'Doe'); // Specifying a default value
$column3 = new Column('email', null, 'user_email'); // Specifying a custom database column name

columnsMapping()方法具有双重用途：它定义了模型属性的列名映射，允许您指定在SELECT操作期间要搜索的列，同时使您能够设置这些属性的默认值。

《columnsMapping()` 方法应始终包含 PrimaryKeyColumn 对象，这对于在数据库中识别用于搜索元素的唯一列至关重要。在 columnsMapping() 方法中应只定义一个 PrimaryKeyColumn 对象。

static protected function columnsMapping(): array
{
    return [
        new PrimaryKeyColumn('id'),
        new Column('firstname'),
        new Column('lastname'),
        new Column('email'),
        new Column('password'),
        new Column('isActive', false, 'is_active'),
    ];
}

在这个示例中，User 模型中的 isActive 属性对应于数据库表中的列名 is_active。当获取或插入数据时，ORM 将自动使用定义的映射将属性名称映射到相应的列名称。

例如，当你插入一个新的 User 实例时

$user = new User([
    'firstname' => 'John',
    'lastname' => 'Doe',
    'isActive' => true,
]);
$userRepository->insert($user);

columnsMapping() 方法至关重要，因为它定义了模型属性列名映射。这种映射是必要的，因为它指定了模型属性如何与数据库表中的列对应。默认情况下，ORM 会尝试将每个属性与数据库中同名的列关联起来。然而，在模型中的属性名称与相应的数据库列名称不同的情况下，可以使用 Column 对象来指定自定义映射，如示例所示：new Column('isActive', false, 'is_active')。

当然，这里有一个用于持久化、删除和刷新的附加部分

持久化、删除和刷新

ASLinkORM 提供了用于持久化实体、删除实体和刷新更改到底层数据库的方法。这些方法对于管理实体的生命周期和确保更改与数据库正确同步至关重要。

持久化

persist 方法允许你将实体标记为插入到数据库中。当你对实体调用 persist 时，ASLinkORM 会跟踪它，并在稍后的刷新操作中将其包括在内。

use AlphaSoft\AsLinkOrm\Entity\AsEntity;

// Assuming $entityManager is an instance of EntityManager
$user = new User([
    'firstname' => 'John',
    'lastname' => 'Doe',
    'email' => 'john@example.com',
]);

$entityManager->persist($user);

删除

remove 方法允许你将实体标记为从数据库中删除。当你对实体调用 remove 时，ASLinkORM 会跟踪它，并在稍后的刷新操作中将其包括在内。

use AlphaSoft\AsLinkOrm\Entity\AsEntity;

// Assuming $entityManager is an instance of EntityManager
$user = $userRepository->findOneBy(['id' => 1]);

$entityManager->remove($user);

刷新

flush 方法将跟踪的实体的更改与底层数据库同步。它执行挂起的插入、更新和删除操作，确保数据库反映实体的当前状态。

use AlphaSoft\AsLinkOrm\EntityManager;

// Assuming $entityManager is an instance of EntityManager
$entityManager->flush();

通过使用这些方法，你可以管理应用程序中实体的持久化和删除，确保更改与数据库正确同步。

现在，开发者可以利用这些方法来有效地管理实体生命周期并在其应用程序中确保数据完整性。

请随意将此部分纳入您的 README，以提供关于使用 ASLinkORM 的全面指导。

调试 SQL 查询

SqlDebugger 是 AsLinkORM 中的 EntityManager 包含的一个方便的实用程序类。它允许开发者轻松地调试应用程序执行 SQL 查询。在交互 EntityManager 时，开发者可以通过 SqlDebugger 获取关于查询执行时间和参数的见解，有助于识别和解决与数据库相关的问题。

访问 SqlDebugger

开发者可以通过 EntityManager 类访问 SqlDebugger 进行调试。一旦实例化 EntityManager，就可以使用 getConnection() 方法检索与其关联的 SqlDebugger 实例。

use AlphaSoft\AsLinkOrm\EntityManager;

// Instantiate the EntityManager with database parameters
$entityManager = new EntityManager($params);

// Retrieve the SqlDebugger instance
$sqlDebugger = $entityManager->getConnection()->getSqlDebugger();

一旦获得 SqlDebugger 实例，开发者就可以利用其方法检索关于执行 SQL 查询及其执行时间的信息。

示例用法

use AlphaSoft\AsLinkOrm\EntityManager;

// Instantiate the EntityManager with database parameters
$entityManager = new EntityManager($params);

// Retrieve the SqlDebugger instance
$sqlDebugger = $entityManager->getConnection()->getSqlDebugger();

// Execute SQL queries using EntityManager
// ...

// Retrieve and display debug information
$queries = $sqlDebugger->getQueries();

foreach ($queries as $queryInfo) {
    echo "Query: " . $queryInfo['query'] . "\n";
    echo "Parameters: " . implode(', ', $queryInfo['params']) . "\n";
    echo "Execution Time: " . $queryInfo['executionTime'] . " seconds\n";
    echo "\n";
}

通过遵循以下步骤，开发者可以使用 AsLinkORM 提供的集成 SqlDebugger 类在应用程序中有效地调试 SQL 查询。

贡献

如果您想为 ASLinkORM 做贡献，请随意在 GitHub 仓库中打开 pull requests 和 issues。

许可

ASLinkORM 是开源软件，根据 MIT 许可证授权。