Pheasant 项目技术文档

1. 安装指南

1.1 使用 Composer 安装

Pheasant 项目推荐使用 Composer 进行安装。Composer 是 PHP 的依赖管理工具，能够方便地管理项目的依赖关系。

安装步骤：

1. 确保你已经安装了 Composer。如果尚未安装，可以通过以下命令进行安装：

   curl -sS https://getcomposer.org/installer | php
   mv composer.phar /usr/local/bin/composer
   

2. 在你的项目根目录下创建或编辑 composer.json 文件，添加 Pheasant 作为依赖：

   {
     "require": {
       "lox/pheasant": "*"
     }
   }
   

3. 运行以下命令安装 Pheasant：

   composer require lox/pheasant
   

4. 安装完成后，Composer 会自动下载并安装 Pheasant 及其依赖包。

2. 项目的使用说明

2.1 配置数据库连接

在使用 Pheasant 之前，需要配置数据库连接。可以通过 Pheasant::setup 方法来设置数据库连接信息。

<?php
use \Pheasant;

// 配置数据库连接
Pheasant::setup('mysql://localhost:/mydatabase');

// 你可以添加额外选项：
// Pheasant::setup('mysql://root@localhost:/mydatabase?charset=utf8'); (utf8 是默认值)
// Pheasant::setup('mysql://root:password@localhost:/mydatabase?ssl_ca=foobar.pem');

2.2 定义域对象

Pheasant 使用域对象来映射数据库表。每个域对象都有一组属性和关系，这些属性和关系在 properties 和 relationships 方法中定义。

<?php
use \Pheasant;
use \Pheasant\Types;

class Post extends DomainObject
{
  public function properties()
  {
    return array(
      'postid'   => new Types\SequenceType(),
      'title'    => new Types\StringType(255, 'required'),
      'subtitle' => new Types\StringType(255),
      'status'   => new Types\EnumType(array('closed','open')),
      'authorid' => new Types\IntegerType(11),
      );
  }

  public function relationships()
  {
    return array(
      'Author' => Author::hasOne('authorid')
    );
  }
}

class Author extends DomainObject
{
  public function properties()
  {
    return array(
      'authorid' => new Types\SequenceType(),
      'fullname' => new Types\StringType(255, 'required')
    );
  }

  public function relationships()
  {
    return array(
      'Posts' => Post::hasOne('authorid')
    );
  }
}

2.3 保存对象

定义好域对象后，可以通过 save 方法将对象保存到数据库中。

<?php
// 创建一些对象
$author = new Author(array('fullname'=>'Lachlan'));
$post = new Post(array('title'=>'My Post', 'author'=>$author));

// 保存对象
$author->save();
$post->save();

echo $post->title; // 返回 'My Post'
echo $post->Author->fullname; // 返回 'Lachlan'

3. 项目API使用文档

3.1 魔法查找器

Pheasant 提供了多种查找器来定位对象。

<?php
// 所有用户
$users = User::all();

// 所有名为 frank 的用户
$users = User::find('firstname = ?', 'frank');

// 任何字段都可以用于查找器，这会转换为上面的查询
$users = User::findByFirstName('frank');

// 一个名为 frank 的用户
$users = User::one('firstname = ?', 'frank');

// 通过主键查找用户
$user = User::byId(1);

// 一个用户的所有评论（如果用户有多个评论）
$comments = User::byId(1)->Comment;

// 为了避免 n+1 查询问题，可以预加载关系：
$users = User::all()->includes(['Comment']); // $users[0]->Comment 不会触发数据库查询

// 预加载还支持预加载子关系
$users = User::all()->includes(['Comment' => [ 'Like', ]]);

3.2 集合作用域

作用域允许你定义常用的查询，这些查询可以通过方法调用在集合对象上引用。所有作用域方法都将返回一个 Pheasant::Collection 对象，允许进一步调用其他方法。

use \Pheasant;
Class User extends DomainObject
{
  public function scopes()
  {
    return array(
      'active' => function($collection){
        $collection->filter('last_login_date >= ?', strtotime('30 days ago'));
      },
    );
  }
}

// 作用域可以通过方法调用使用
User::all()->active()
//=> 返回所有活跃用户

3.3 事件

Pheasant 支持在创建、更新和删除操作之前和之后触发代码。

<?php
use \Pheasant;
use \Pheasant\Events;
use \Pheasant\Types;

class Post extends DomainObject
{
  public function properties()
  {
    return array(
      'postid'      => new Types\SequenceType(),
      'title'       => new Types\StringType(255),
      'timecreated' => new Types\IntegerType(11),
      ));
  }

  public function beforeCreate($post)
  {
    $d->timecreated = time();
  }
}

3.4 事务

Pheasant 支持全局事务和实例事务。

<?php
// 全局事务
\Pheasant::transaction(function() {
  $post = new Post(array('title'=>'First Post!'));
  $post->save();
});

// 实例事务
$post = new Post(array('title'=>'First Post!'));
$post->transaction(function($obj) {
  $obj->save();
});

4. 项目安装方式

Pheasant 项目可以通过 Composer 进行安装，具体步骤请参考 安装指南。