【译】Let’s Encrypt – 免费的SSL/TLS证书

每一个建立过安全站点的人都在如何维护证书这个问题上深受困扰。Let’s Encrypt 推荐的客户端 Certbot,能够自动的消除这些用户的痛点,并且让站点维护人员能够使用简单的命令开启和管理站点的HTTPS功能。

不需要验证邮件,不需要去编辑复杂的配置,也不再你的站点因为证书过期而无法正常工作。当然,因为Let’s Encrypt提供的是免费证书,因此也不需要付费。

本文简要描述了如何使用Certbot进行证书管理。(欢迎使用任何兼容的客户端;相关说明请查看这些项目的指导页面)。

如果你想知道更多关于它是工作原理,查看我们的 工作原理 页面。

安装客户端软件

如果你的操作系统包含了一个certbot的安装包,从这里安装它 ,然后使用相应的certbot命令。如果没有的话,则可以使用我们提供的cert-auto包装器脚本快速的获取一份。

$ git clone https://github.com/certbot/certbot
$ cd certbot
$ ./certbot-auto --help 

certbot-autocertbot命令拥有相同的命令行参数;它会安装所有的依赖并且自动更新 Certbot 的代码(这个过程下载的文件比较大,因此比较慢)。

使用限制

Let’s Encrypt 每周会产生有限数量的证书,确切的数量请查看这篇文章。如果你第一次使用certbot,你可能希望添加--test-cert标识,并且使用一个未使用的域名。这样将会从staging服务器获得一个证书,它们在浏览器中是无效的,除此之外,其它过程都是相同的,因此你可以测试各种配置选项而不会超过这个数量限制。

如何使用客户端

Cerbot 支持很多插件,可以用它们来获取和安装证书。下面包含了一些选项的使用例子:

如果你在近期发布的Debian操作系统上运行Apache服务,你可以尝试Apache插件,使用它可以自动获取和安装证书:

certbot --apache

目前在其它平台上还没有实现自动安装,因此你必须使用命令certonly进行安装。下面是一些例子:

要获取一个可以在任何web服务器的webroot目录上能够运行证书,需要使用“webroot”插件:

certbot certonly --webroot -w /var/www/example -d example.com -d www.example.com -w /var/www/thing -d thing.is -d m.thing.is

这个命令将会获取example.com,www.example.com, thing.is 和 m.thing.is 的单个证书,它将会把前两个域名生成的文件放到/var/www/example目录,后面两个放到/var/www/thing目录。

例如使用内建的“独立”web服务器获取 example.com 和 www.example.com 的证书(你可能需要临时停止已经存在的web服务器):

certbot certonly --standalone -d example.com -d www.example.com

证书续订

从0.4.0版本开始,Certbot增加了高级的renew子命令,它可以用于使用之前获取证书时相同的配置续订所有的证书。你可以通过运行以下命令测试一下:

certbot renew --dry-run

上述命令会获取一个测试证书,它不会对你的系统产生任何持久化的修改。如果你觉得这个结果还可以,可以运行下面的命令:

certbot renew

如果你想续订某一个证书(而不是所有的)或者修改某一个用于续订的配置参数,你可以使用certbot certonly命令和其它特定的配置获取单个证书。当使用certbot certonly命令的时候,你可以得到单个证书的续订。使用指定-d选项指定你希望续订的域名所覆盖的每一个域名。

注意: 从0.4.0开始,Certbot将会记录任何你使用certonlyrenew时选择的配置,未来使用renew的时候将会使用最近的配置。在版本0.3.0中,Certbot只会记录第一次获取证书时的配置,并不会使用之后续订时的配置替换它。

动词renew被设计用来半自动或者自动的使用,因此它也隐含着--non-interactive的意味。该选项意味着Certbot不会停下来与你进行交互;对于自动续订来说,使用该选项是非常不错的,但是因为指定该选项的话你无法与Certbot进行交互,因此你应该确保你所有的配置都被正确的设置。

选项--dry-run用于从我们的staging服务器获取证书。获取的证书不会保存到磁盘上,并且你的配置也不会被更新,因此你可以用来测试是否的renew或者certonly命令能够正确的执行续订。从staging服务器获取证书不会影响生产服务器的数量限制。

如果你想要改变之前指定的值,你可以在续订时,在命令行中指定一个新的选项,例如:

certbot renew --rsa-key-size 4096

运行certbot renew命令将会续订所有在续订窗口的证书(默认情况下,证书过期时间为30天)。如果你想要续订单个证书,你应该使用certbot certonly -d命令指定要续订的证书的域名。例如:

certbot certonly --keep-until-expiring --webroot -w /var/www/example.com -d example.com,www.example.com -w /var/www/thing -d thing.is,m.thing.is

如果你的证书安装在本地服务器,则一旦certonly命令执行完成,你需要重载服务器的配置文件(例如,对于apache2服务器来说执行server apache2 reload命令)。

开发自己的续订脚本

对于如何建立自动续订功能,请参考续订文档

撤销证书

使用下面的命令撤销撤销一个证书

$ certbot revoke --cert-path example-cert.pem

完整文档

更多关于Certbot的信息,请参考 完整文档。已知的一些问题使用Github进行跟踪。在提交新的问题的时候请先参考最近是否有相似的问题。

获得帮助

在阅读文档和问题列表之后,如果你需要额外的帮助的话,请尝试我们的帮助社区论坛

查看我们的 隐私策略.

查看我们的 商标策略.

Let’s Encrypt是由非营利的互联网安全研究小组(ISRG)管理的一个免费,自动化,开放的证书授权机构。

1 Letterman Drive, Suite D4700, San Francisco, CA 94129

Linux Foundation是Linux基金会的注册商标。Linux是由Linus Torvalds注册的商标


原文:

Let's Encrypt – Getting Started

研发团队GIT开发流程新人学习指南

分支流程说明

简介

项目中长期存在的两个分支

  • master:主分支,负责记录上线版本的迭代,该分支代码与线上代码是完全一致的。
  • develop:开发分支,该分支记录相对稳定的版本,所有的feature分支和bugfix分支都从该分支创建。

其它分支为短期分支,其完成功能开发之后需要删除

  • feature/*:特性(功能)分支,用于开发新的功能,不同的功能创建不同的功能分支,功能分支开发完成并自测通过之后,需要合并到 develop 分支,之后删除该分支。
  • bugfix/*:bug修复分支,用于修复不紧急的bug,普通bug均需要创建bugfix分支开发,开发完成自测没问题后合并到 develop 分支后,删除该分支。
  • release/*:发布分支,用于代码上线准备,该分支从develop分支创建,创建之后由测试同学发布到测试环境进行测试,测试过程中发现bug需要开发人员在该release分支上进行bug修复,所有bug修复完后,在上线之前,需要合并该release分支到master分支和develop分支。
  • hotfix/*:紧急bug修复分支,该分支只有在紧急情况下使用,从master分支创建,用于紧急修复线上bug,修复完成后,需要合并该分支到master分支以便上线,同时需要再合并到develop分支。

必读文章

团队中的 Git 实践
Git 在团队中的最佳实践–如何正确使用Git Flow

分支命令规范

特性(功能)分支

功能分支的分支名称应该为能够准确描述该功能的英文简要表述

feature/分支名称

例如,开发的功能为 新增商品到物料库,则可以创建名称为 feature/material-add的分支。

bug修复分支、紧急bug修复分支

bug修复分支的分支名称可以为Jira中bug代码或者是描述该bug的英文简称

bugfix/分支名称
hotfix/分支名称

比如,修复的bug在jira中代号为MATERIAL-1,则可以创建一个名为bugfix/MATERIAL-1的分支。

release分支

release分支为预发布分支,命名为本次发布的主要功能英文简称

release/分支名称

比如,本次上线物料库新增的功能,则分支名称可以为release/material-add

常用操作命令简介

基本操作

基本命令这里就不多说了,基本跟以前一样,唯一的区别是注意分支是从哪里拉去的以及分支的命名规范。涉及到的命令主要包含以下,大家自己学习:

  • git commit
  • git add [–all]
  • git push
  • git pull
  • git branch [-d]
  • git merge
  • git cherry-pick
  • git checkout [-b] BRANCH_NAME
  • git stash

分支操作参考 Git常用操作-分支管理

使用git flow简化操作

git flow是git的一个插件,可以极大程度的简化执行git标准分支流程的操作,可以在gitflow-avh安装。

如果是windows下通过安装包安装的git,则该插件默认已经包含,可以直接使用。

初始化

使用git flow init初始化项目

$ git flow init

Which branch should be used for bringing forth production releases?
   - develop
   - feature-fulltext
   - feature-vender
   - master
Branch name for production releases: [master]

Which branch should be used for integration of the "next release"?
   - develop
   - feature-fulltext
   - feature-vender
Branch name for "next release" development: [develop]

How to name your supporting branch prefixes?
Feature branches? [feature/]
Bugfix branches? [bugfix/]
Release branches? [release/]
Hotfix branches? [hotfix/]
Support branches? [support/]
Version tag prefix? []
Hooks and filters directory? [/Users/mylxsw/codes/work/e-business-3.0/.git/hooks]

功能分支

git flow feature
git flow feature start <name>
git flow feature finish <name>
git flow feature delete <name>

git flow feature publish <name>
git flow feature track <name>

功能分支使用例子:

$ git flow feature start material-add
Switched to a new branch 'feature/material-add'

Summary of actions:
- A new branch 'feature/material-add' was created, based on 'develop'
- You are now on branch 'feature/material-add'

Now, start committing on your feature. When done, use:

     git flow feature finish material-add

$ git status
On branch feature/material-add
nothing to commit, working directory clean
$ git flow feature publish
Total 0 (delta 0), reused 0 (delta 0)
To http://dev.oss.yunsom.cn:801/yunsom/e-business-3.0.git
 * [new branch]      feature/material-add -> feature/material-add
Branch feature/material-add set up to track remote branch feature/material-add from origin.
Already on 'feature/material-add'
Your branch is up-to-date with 'origin/feature/material-add'.

Summary of actions:
- The remote branch 'feature/material-add' was created or updated
- The local branch 'feature/material-add' was configured to track the remote branch
- You are now on branch 'feature/material-add'

$ vim README.md
$ git add --all
$ git commit -m "modify readme file "
[feature/material-add 7235bd4] modify readme file
 1 file changed, 1 insertion(+), 2 deletions(-)
$ git push
Counting objects: 3, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 303 bytes | 0 bytes/s, done.
Total 3 (delta 2), reused 0 (delta 0)
To http://dev.oss.yunsom.cn:801/yunsom/e-business-3.0.git
   0d4fb8f..7235bd4  feature/material-add -> feature/material-add
$ git flow feature finish
Switched to branch 'develop'
Your branch is up-to-date with 'origin/develop'.
Updating 0d4fb8f..7235bd4
Fast-forward
 README.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)
To http://dev.oss.yunsom.cn:801/yunsom/e-business-3.0.git
 - [deleted]         feature/material-add
Deleted branch feature/material-add (was 7235bd4).

Summary of actions:
- The feature branch 'feature/material-add' was merged into 'develop'
- Feature branch 'feature/material-add' has been locally deleted; it has been remotely deleted from 'origin'
- You are now on branch 'develop'

$ git branch
* develop
  feature-fulltext
  feature-vender
  master

预发布分支

git flow release
git flow release start <release> [<base>]
git flow release finish <release>
git flow release delete <release>

hotfix分支

git flow hotfix
git flow hotfix start <release> [<base>]
git flow hotfix finish <release>
git flow hotfix delete <release>

git-flow 备忘清单

参考git-flow 备忘清单

总结

如果上面内容太多记不住,也没有关系,作为开发人员,刚开始的时候只要知道以下几点就足够了,其它的可以在碰到的时候再深入学习:

  • 所有的新功能开发,bug修复(非紧急)都要从develop分支拉取新的分支进行开发,开发完成自测没有问题再合并到develop分支
  • release分支发布到测试环境,由开发人员创建release分支(需要测试人员提出需求)并发布到测试环境,如果测试过程中发现bug,需要开发人员track到该release分支修复bug,上线前需要测试人员提交merge requestmaster分支,准备上线,同时需要合并回develop分支。
  • 只有紧急情况下才允许从master上拉取hotfix分支,hotfix分支需要最终同时合并到developmaster分支(共两次merge操作)
  • 除了masterdevelop分支,其它分支在开发完成后都要删除

Unix系统服务监控 Monit

Monit 是Unix系统中用于管理和监控进程、程序、文件、目录和文件系统的工具。使用 Monit 可以检测进程是否正常运行,如果异常可以自动重启服务以及报警,当然,也可以使用 Monit 检查文件和目录是否发生修改,例如时间戳、校验和以及文件大小的改变。

常用操作

Monit 默认的配置文件是~/.monitrc,如果没有该文件,则使用/etc/monitrc文件。在启动 Monit 的时候,可以指定使用的配置文件:

$ monit -c /var/monit/monitrc

在第一次启动 monit 的使用,可以使用如下命令测试配置文件(控制文件)是否正确

$ monit -t
$ Control file syntax OK

如果配置文件没有问题的话,就可以使用monit命令启动 monit 了。

Continue reading →

Linux 配置安装MySQL

废话不多说,虽然可以通过yum直接安装MySQL,但是为了能够对安装过程有一个比较清晰的认识,
我们这里还是使用源码编译安装。

$ wget http://dev.mysql.com/get/Downloads/MySQL-5.6/mysql-5.6.21.tar.gz
$ tar -zxvf mysql-5.6.21.tar.gz
$ cd mysql-5.6.21

文件已经下载并且解压好了,在安装之前,我们需要为mysql建立名为mysql的用户名和用户组。

$ sudo groupadd mysql
$ sudo useradd -r -g mysql mysql

Continue reading →

跟我一起学Laravel-常见问题

如何在页面中输出所有的表单错误

@if (count($errors) > 0)
    @foreach ($errors->toArray() as $err)
        {{ current($err) }}
    @endforeach
@endif

使用Lumen操作MySQL出现时间比本地时间多了8小时

在Lumen中设置时区需要两个设置,一个是应用的设置,还有一个是数据库的设置.

DB_TIMEZONE=+08:00
APP_TIMEZONE=PRC

如何修改storage目录

线上环境肯定是不希望storage目录在项目目录下的,修改storage目录需要新建一个配置文件path.php,增加以下配置

<?php
return [
    'storage' => '/home/data/storage',
]; 

如何获取当前路由的名称(命名路由)

\Route::getCurrentRoute()->getName()

跟我一起学Laravel-EloquentORM高级部分

查询作用域

全局作用域

全局作用域允许你对给定模型的所有查询添加约束。使用全局作用域功能可以为模型的所有操作增加约束。

软删除功能实际上就是利用了全局作用域功能

实现一个全局作用域功能只需要定义一个实现Illuminate\Database\Eloquent\Scope接口的类,该接口只有一个方法apply,在该方法中增加查询需要的约束

<?php

namespace App\Scopes;

use Illuminate\Database\Eloquent\Scope;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Builder;

class AgeScope implements Scope
{
    /**
     * Apply the scope to a given Eloquent query builder.
     *
     * @param  \Illuminate\Database\Eloquent\Builder  $builder
     * @param  \Illuminate\Database\Eloquent\Model  $model
     * @return void
     */
    public function apply(Builder $builder, Model $model)
    {
        return $builder->where('age', '>', 200);
    }
}

在模型的中,需要覆盖其boot方法,在该方法中增加addGlobalScope

<?php

namespace App;

use App\Scopes\AgeScope;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * The "booting" method of the model.
     *
     * @return void
     */
    protected static function boot()
    {
        parent::boot();

        static::addGlobalScope(new AgeScope);
    }
}

添加全局作用域之后,User::all()操作将会产生如下等价sql

select * from users where age > 200

也可以使用匿名函数添加全局约束

static::addGlobalScope('age', function(Builder $builder) {
  $builder->where('age', '>', 200);
});

查询中要移除全局约束的限制,使用withoutGlobalScope方法

// 只移除age约束
User::withoutGlobalScope('age')->get();
User::withoutGlobalScope(AgeScope::class)->get();
// 移除所有约束
User::withoutGlobalScopes()->get();
// 移除多个约束
User::withoutGlobalScopes([FirstScope::class, SecondScope::class])->get();

本地作用域

本地作用域只对部分查询添加约束,需要手动指定是否添加约束,在模型中添加约束方法,使用前缀scope

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * Scope a query to only include popular users.
     *
     * @return \Illuminate\Database\Eloquent\Builder
     */
    public function scopePopular($query)
    {
        return $query->where('votes', '>', 100);
    }

    /**
     * Scope a query to only include active users.
     *
     * @return \Illuminate\Database\Eloquent\Builder
     */
    public function scopeActive($query)
    {
        return $query->where('active', 1);
    }
}

使用上述添加的本地约束查询,只需要在查询中使用scope前缀的方法,去掉scope前缀即可

$users = App\User::popular()->active()->orderBy('created_at')->get();

本地作用域方法是可以接受参数的

public function scopeOfType($query, $type)
{
    return $query->where('type', $type);
}

调用的时候

$users = App\User::ofType('admin')->get();

事件

Eloquent模型会触发下列事件

creating, created, updating, updated, saving, saved,deleting, deleted, restoring, restored

使用场景

假设我们希望保存用户的时候对用户进行校验,校验通过后才允许保存到数据库,可以在服务提供者中为模型的事件绑定监听

<?php

namespace App\Providers;

use App\User;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Bootstrap any application services.
     *
     * @return void
     */
    public function boot()
    {
        User::creating(function ($user) {
            if ( ! $user->isValid()) {
                return false;
            }
        });
    }

    /**
     * Register the service provider.
     *
     * @return void
     */
    public function register()
    {
        //
    }
}

上述服务提供者对象中,在框架启动时会监听模型的creating事件,当保存用户之间检查用户数据的合法性,如果不合法,返回false,模型数据不会被持久化到数据。

返回false会阻止模型的save / update操作

序列化

当构建JSON API的时候,经常会需要转换模型和关系为数组或者json。Eloquent提供了一些方法可以方便的来实现数据类型之间的转换。

转换模型/集合为数组 – toArray()

$user = App\User::with('roles')->first();
return $user->toArray();

$users = App\User::all();
return $users->toArray();

转换模型为json – toJson()

$user = App\User::find(1);
return $user->toJson();

$user = App\User::find(1);
return (string) $user;

隐藏属性

有时某些字段不应该被序列化,比如用户的密码等,使用$hidden字段控制那些字段不应该被序列化

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * The attributes that should be hidden for arrays.
     *
     * @var array
     */
    protected $hidden = ['password'];
}

隐藏关联关系的时候,使用的是它的方法名称,不是动态的属性名

也可以使用$visible指定会被序列化的白名单

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * The attributes that should be visible in arrays.
     *
     * @var array
     */
    protected $visible = ['first_name', 'last_name'];
}

有时可能需要某个隐藏字段被临时序列化,使用makeVisible方法

return $user->makeVisible('attribute')->toArray();

为json追加值

有时需要在json中追加一些数据库中不存在的字段,使用下列方法,现在模型中增加一个get方法

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{

    /**
     * The accessors to append to the model's array form.
     *
     * @var array
     */
    protected $appends = ['is_admin'];


    /**
     * Get the administrator flag for the user.
     *
     * @return bool
     */
    public function getIsAdminAttribute()
    {
        return $this->attributes['admin'] == 'yes';
    }
}

方法签名为getXXXAttribute格式,然后为模型的$appends字段设置字段名。

Mutators

在Eloquent模型中,Accessor和Mutator可以用来对模型的属性进行处理,比如我们希望存储到表中的密码字段要经过加密才行,我们可以使用Laravel的加密工具自动的对它进行加密。

Accessors & Mutators

accessors

要定义一个accessor,需要在模型中创建一个名称为getXxxAttribute的方法,其中的Xxx是驼峰命名法的字段名。

假设我们有一个字段是first_name,当我们尝试去获取first_name的值的时候,getFirstNameAttribute方法将会被自动的调用

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * Get the user's first name.
     *
     * @param  string  $value
     * @return string
     */
    public function getFirstNameAttribute($value)
    {
        return ucfirst($value);
    }
}

在访问的时候,只需要正常的访问属性就可以

$user = App\User::find(1);
$firstName = $user->first_name;

mutators

创建mutators与accessorsl类似,创建名为setXxxAttribute的方法即可

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * Set the user's first name.
     *
     * @param  string  $value
     * @return string
     */
    public function setFirstNameAttribute($value)
    {
        $this->attributes['first_name'] = strtolower($value);
    }
}

赋值方式

$user = App\User::find(1);
$user->first_name = 'Sally';

属性转换

模型的$casts属性提供了一种非常简便的方式转换属性为常见的数据类型,在模型中,使用$casts属性定义一个数组,该数组的key为要转换的属性名称,value为转换的数据类型,当前支持integer, real, float, double, string, boolean, object, array,collection, date, datetime, 和 timestamp

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * The attributes that should be casted to native types.
     *
     * @var array
     */
    protected $casts = [
        'is_admin' => 'boolean',
    ];
}

数组类型的转换时非常有用的,我们在数据库中存储json数据的时候,可以将其转换为数组形式。

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * The attributes that should be casted to native types.
     *
     * @var array
     */
    protected $casts = [
        'options' => 'array',
    ];
}

从配置数组转换的属性取值或者赋值的时候都会自动的完成json和array的转换

$user = App\User::find(1);  
$options = $user->options;
$options['key'] = 'value';
$user->options = $options;
$user->save();

参考:

跟我一起学Laravel-EloquentORM进阶部分

关联关系

One To One

假设User模型关联了Phone模型,要定义这样一个关联,需要在User模型中定义一个phone方法,该方法返回一个hasOne方法定义的关联

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * Get the phone record associated with the user.
     */
    public function phone()
    {
        return $this->hasOne('App\Phone');
    }
}

hasOne方法的第一个参数为要关联的模型,定义好之后,可以使用下列语法查询到关联属性了

$phone = User::find(1)->phone;

Eloquent会假定关联的外键是基于模型名称的,因此Phone模型会自动使用user_id字段作为外键,可以使用第二个参数和第三个参数覆盖

return $this->hasOne('App\Phone', 'foreign_key');
return $this->hasOne('App\Phone', 'foreign_key', 'local_key');

定义反向关系

定义上述的模型之后,就可以使用User模型获取Phone模型了,当然也可以通过Phone模型获取所属的User了,这就用到了belongsTo方法了

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Phone extends Model
{
    /**
     * Get the user that owns the phone.
     */
    public function user()
    {
        return $this->belongsTo('App\User');
        // return $this->belongsTo('App\User', 'foreign_key');
        // return $this->belongsTo('App\User', 'foreign_key', 'other_key');

    }
}

One To Many

假设有一个帖子,它有很多关联的评论信息,这种情况下应该使用一对多的关联,使用hasMany方法

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    /**
     * Get the comments for the blog post.
     */
    public function comments()
    {
        return $this->hasMany('App\Comment');
    }
}

查询操作

$comments = App\Post::find(1)->comments;
foreach ($comments as $comment) {
    //
}

$comments = App\Post::find(1)->comments()->where('title', 'foo')->first();

定义反向关联

反向关联也是使用belongsTo方法,参考One To One部分。

$comment = App\Comment::find(1);
echo $comment->post->title;

Many To Many

多对多关联因为多了一个中间表,实现起来比hasOnehasMany复杂一些。

考虑这样一个场景,用户可以属于多个角色,一个角色也可以属于多个用户。这就引入了三个表: users, roles, role_user。其中role_user表为关联表,包含两个字段user_idrole_id

多对多关联需要使用belongsToMany方法

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * The roles that belong to the user.
     */
    public function roles()
    {
        // 指定关联表
        // return $this->belongsToMany('App\Role', 'role_user');
        // 指定关联表,关联字段
        // return $this->belongsToMany('App\Role', 'role_user', 'user_id', 'role_id');

        return $this->belongsToMany('App\Role');
    }
}

上述定义了一个用户属于多个角色,一旦该关系确立,就可以查询了

$user = App\User::find(1);
foreach ($user->roles as $role) {
    //
}

$roles = App\User::find(1)->roles()->orderBy('name')->get();

反向关联关系

反向关系与正向关系实现一样

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Role extends Model
{
    /**
     * The users that belong to the role.
     */
    public function users()
    {
        return $this->belongsToMany('App\User');
    }
}

检索中间表的列值

对多对多关系来说,引入了一个中间表,因此需要有方法能够查询到中间表的列值,比如关系确立的时间等,使用pivot属性查询中间表

$user = App\User::find(1);

foreach ($user->roles as $role) {
    echo $role->pivot->created_at;
}

上述代码访问了中间表的created_at字段。

注意的是,默认情况下之后模型的键可以通过pivot对象进行访问,如果中间表包含了额外的属性,在指定关联关系的时候,需要使用withPivot方法明确的指定列名

return $this->belongsToMany('App\Role')->withPivot('column1', 'column2');

如果希望中间表自动维护created_atupdated_at字段的话,需要使用withTimestamps()

return $this->belongsToMany('App\Role')->withTimestamps();

Has Many Through

这种关系比较强大,假设这样一个场景:Country模型下包含了多个User模型,而每个User模型又包含了多个Post模型,也就是说一个国家有很多用户,而这些用户都有很多帖子,我们希望查询某个国家的所有帖子,怎么实现呢,这就用到了Has Many Through关系

countries
    id - integer
    name - string

users
    id - integer
    country_id - integer
    name - string

posts
    id - integer
    user_id - integer
    title - string

可以看到,posts表中并不直接包含country_id,但是它通过users表与countries表建立了关系

使用Has Many Through关系

namespace App;

use Illuminate\Database\Eloquent\Model;

class Country extends Model
{
    /**
     * Get all of the posts for the country.
     */
    public function posts()
    {
        // return $this->hasManyThrough('App\Post', 'App\User', 'country_id', 'user_id');

        return $this->hasManyThrough('App\Post', 'App\User');
    }
}

方法hasManyThrough的第一个参数是我们希望访问的模型名称,第二个参数是中间模型名称。

HasManyThrough hasManyThrough( 
    string $related, 
    string $through, 
    string|null $firstKey = null, 
    string|null $secondKey = null, 
    string|null $localKey = null
)

Polymorphic Relations (多态关联)

多态关联使得同一个模型使用一个关联就可以属于多个不同的模型,假设这样一个场景,我们有一个帖子表和一个评论表,用户既可以对帖子执行喜欢操作,也可以对评论执行喜欢操作,这样的情况下该怎么处理呢?

表结构如下

posts
    id - integer
    title - string
    body - text

comments
    id - integer
    post_id - integer
    body - text

likes
    id - integer
    likeable_id - integer
    likeable_type - string

可以看到,我们使用likes表中的likeable_type字段判断该记录喜欢的是帖子还是评论,表结构有了,接下来就该定义模型了

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Like extends Model
{
    /**
     * Get all of the owning likeable models.
     */
    public function likeable()
    {
        return $this->morphTo();
    }
}

class Post extends Model
{
    /**
     * Get all of the product's likes.
     */
    public function likes()
    {
        return $this->morphMany('App\Like', 'likeable');
    }
}

class Comment extends Model
{
    /**
     * Get all of the comment's likes.
     */
    public function likes()
    {
        return $this->morphMany('App\Like', 'likeable');
    }
}

默认情况下,likeable_type的类型是关联的模型的完整名称,比如这里就是App\PostApp\Comment

通常情况下我们可能会使用自定义的值标识关联的表名,因此,这就需要自定义这个值了,我们需要在项目的服务提供者对象的boot方法中注册关联关系,比如AppServiceProviderboot方法中

use Illuminate\Database\Eloquent\Relations\Relation;

Relation::morphMap([
    'posts' => App\Post::class,
    'likes' => App\Like::class,
]);

检索多态关系

访问一个帖子所有的喜欢

$post = App\Post::find(1);  
foreach ($post->likes as $like) {
    //
}

访问一个喜欢的帖子或者评论

$like = App\Like::find(1);   
$likeable = $like->likeable;

上面的例子中,返回的likeable会根据该记录的类型返回帖子或者评论。

多对多的多态关联

多对多的关联使用方法morphToManymorphedByMany,这里就不多废话了。

关联关系查询

在Eloquent中,所有的关系都是使用函数定义的,可以在不执行关联查询的情况下获取关联的实例。假设我们有一个博客系统,User模型关联了很多Post模型:

/**
 * Get all of the posts for the user.
 */
public function posts()
{
   return $this->hasMany('App\Post');
}

你可以像下面这样查询关联并且添加额外的约束

$user = App\User::find(1);
$user->posts()->where('active', 1)->get();

如果不需要对关联的属性添加约束,可以直接作为模型的属性访问,例如上面的例子,我们可以使用下面的方式访问User的Post

$user = App\User::find(1);
foreach ($user->posts as $post) {
    //
}

动态的属性都是延迟加载的,它们只有在被访问的时候才会去查询数据库,与之对应的是预加载,预加载可以使用关联查询出所有数据,减少执行sql的数量。

查询关系存在性

使用has方法可以基于关系的存在性返回结果

// 检索至少有一个评论的所有帖子...
$posts = App\Post::has('comments')->get();

// Retrieve all posts that have three or more comments...
$posts = Post::has('comments', '>=', 3)->get();
// Retrieve all posts that have at least one comment with votes...
$posts = Post::has('comments.votes')->get();

如果需要更加强大的功能,可以使用whereHasorWhereHas方法,把where条件放到has语句中。

// 检索所有至少存在一个匹配foo%的评论的帖子
$posts = Post::whereHas('comments', function ($query) {
    $query->where('content', 'like', 'foo%');
})->get();

预加载

在访问Eloquent模型的时候,默认情况下所有的关联关系都是延迟加载的,在使用的时候才会开始加载,这就造成了需要执行大量的sql的问题,使用预加载功能可以使用关联查询出所有结果

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Book extends Model
{
    /**
     * Get the author that wrote the book.
     */
    public function author()
    {
        return $this->belongsTo('App\Author');
    }
}

接下来我们检索所有的书和他们的作者

$books = App\Book::all();

foreach ($books as $book) {
    echo $book->author->name;
}

上面的查询将会执行一个查询查询出所有的书,然后在遍历的时候再执行N个查询查询出作者信息,显然这样做是非常低效的,幸好我们还有预加载功能,可以将这N+1个查询减少到2个查询,在查询的时候,可以使用with方法指定哪个关系需要预加载。

$books = App\Book::with('author')->get();
foreach ($books as $book) {
    echo $book->author->name;
}

对于该操作,会执行下列两个sql

select * from books
select * from authors where id in (1, 2, 3, 4, 5, ...)

预加载多个关系

$books = App\Book::with('author', 'publisher')->get();

嵌套的预加载

$books = App\Book::with('author.contacts')->get();

带约束的预加载

$users = App\User::with(['posts' => function ($query) {
    $query->where('title', 'like', '%first%');
}])->get();

$users = App\User::with(['posts' => function ($query) {
    $query->orderBy('created_at', 'desc');
}])->get();

延迟预加载

有时候,在上级模型已经检索出来之后,可能会需要预加载关联数据,可以使用load方法

$books = App\Book::all();
if ($someCondition) {
    $books->load('author', 'publisher');
}

$books->load(['author' => function ($query) {
    $query->orderBy('published_date', 'asc');
}]);

关联模型插入

save方法

保存单个关联模型

$comment = new App\Comment(['message' => 'A new comment.']);
$post = App\Post::find(1);
$post->comments()->save($comment);

保存多个关联模型

$post = App\Post::find(1); 
$post->comments()->saveMany([
    new App\Comment(['message' => 'A new comment.']),
    new App\Comment(['message' => 'Another comment.']),
]);

save方法和多对多关联

多对多关联可以为save的第二个参数指定关联表中的属性

App\User::find(1)->roles()->save($role, ['expires' => $expires]);

上述代码会更新中间表的expires字段。

create方法

使用create方法与save方法的不同在于它是使用数组的形式创建关联模型的

$post = App\Post::find(1);
$comment = $post->comments()->create([
    'message' => 'A new comment.',
]);

更新 “Belongs To” 关系

更新belongsTo关系的时候,可以使用associate方法,该方法会设置子模型的外键

$account = App\Account::find(10);
$user->account()->associate($account);
$user->save();

要移除belongsTo关系的话,使用dissociate方法

$user->account()->dissociate();
$user->save();

Many to Many 关系

中间表查询条件

当查询时需要对使用中间表作为查询条件时,可以使用wherePivotwherePivotInorWherePivotorWherePivotIn添加查询条件。

$enterprise->with(['favorites' => function($query) {
    $query->wherePivot('enterprise_id', '=', 12)->select('id');
}]);

Attaching / Detaching

$user = App\User::find(1);
// 为用户添加角色
$user->roles()->attach($roleId);
// 为用户添加角色,更新中间表的expires字段
$user->roles()->attach($roleId, ['expires' => $expires]);

// 移除用户的单个角色
$user->roles()->detach($roleId);
// 移除用户的所有角色
$user->roles()->detach();

attachdetach方法支持数组参数,同时添加和移除多个

$user = App\User::find(1);
$user->roles()->detach([1, 2, 3]);
$user->roles()->attach([1 => ['expires' => $expires], 2, 3]);

更新中间表(关联表)字段

使用updateExistingPivot方法更新中间表

$user = App\User::find(1);
$user->roles()->updateExistingPivot($roleId, $attributes);

同步中间表(同步关联关系)

使用sync方法,可以指定两个模型之间只存在指定的关联关系

$user->roles()->sync([1, 2, 3]);
$user->roles()->sync([1 => ['expires' => true], 2, 3]);

上述两个方法都会让用户只存在1,2,3三个角色,如果用户之前存在其他角色,则会被删除。

更新父模型的时间戳

假设场景如下,我们为一个帖子增加了一个新的评论,我们希望这个时候帖子的更新时间会相应的改变,这种行为在Eloquent中是非常容易实现的。

在子模型中使用$touches属性实现该功能

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Comment extends Model
{
    /**
     * All of the relationships to be touched.
     *
     * @var array
     */
    protected $touches = ['post'];

    /**
     * Get the post that the comment belongs to.
     */
    public function post()
    {
        return $this->belongsTo('App\Post');
    }
}

现在,更新评论的时候,帖子的updated_at字段也会被更新

$comment = App\Comment::find(1);
$comment->text = 'Edit to this comment!';
$comment->save();

参考: Eloquent: Relationships

跟我一起学Laravel-EloquentORM基础部分

使用Eloquent [‘eləkwənt] 时,数据库查询构造器的方法对模型类也是也用的,使用上只是省略了DB::table('表名')部分。

在模型中使用protected成员变量$table指定绑定的表名。

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
    /**
     * The table associated with the model.
     *
     * @var string
     */
    protected $table = 'my_flights';
}

Eloquent 假设每个表都有一个名为id的主键,可以通过$primaryKey成员变量覆盖该字段名称,另外,Eloquent假设主键字段是自增的整数,如果你想用非自增的主键或者非数字的主键的话,必须指定模型中的public属性$incrementing为false。

默认情况下,Eloquent期望表中存在created_atupdated_at两个字段,字段类型为timestamp,如果不希望这两个字段的话,设置$timestamps为false

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
    /**
     * Indicates if the model should be timestamped.
     *
     * @var bool
     */
    public $timestamps = false;

    /**
     * The storage format of the model's date columns.
     *
     * @var string
     */
    protected $dateFormat = 'U';
}

使用protected $connection = 'connection-name'指定模型采用的数据库连接。

查询

基本查询操作

方法all用于返回模型表中所有的结果

$flights = Flight::all();
foreach ($flights as $flight) {
    echo $flight->name;
}

也可以使用get方法为查询结果添加约束

$flights = App\Flight::where('active', 1)
     ->orderBy('name', 'desc')
     ->take(10)
     ->get();

可以看到,查询构造器的方法对模型类也是可以使用的

在eloquent ORM中,getall方法查询出多个结果集,它们的返回值是一个Illuminate\Database\Eloquent\Collection对象,该对象提供了多种对结果集操作的方法

public function find($key, $default = null);
public function contains($key, $value = null);
public function modelKeys();
public function diff($items)
...

该对象的方法有很多,这里只列出一小部分,更多方法参考API文档 Collection使用说明文档

对大量结果分段处理,同样是使用chunk方法

Flight::chunk(200, function ($flights) {
    foreach ($flights as $flight) {
        //
    }
});

查询单个结果

使用findfirst方法查询单个结果,返回的是单个的模型实例

// 通过主键查询模型...
$flight = App\Flight::find(1);

// 使用约束...
$flight = App\Flight::where('active', 1)->first();

使用find方法也可以返回多个结果,以Collection对象的形式返回,参数为多个主键

$flights = App\Flight::find([1, 2, 3]);

如果查询不到结果的话,可以使用findOrFail或者firstOrFail方法,这两个方法在查询不到结果的时候会抛出Illuminate\Database\Eloquent\ModelNotFoundException异常

$model = App\Flight::findOrFail(1);
$model = App\Flight::where('legs', '>', 100)->firstOrFail();

如果没有捕获这个异常的话,laravel会自动返回给用户一个404的响应结果,因此如果希望找不到的时候返回404,是可以直接使用该方法返回的

Route::get('/api/flights/{id}', function ($id) {
    return App\Flight::findOrFail($id);
});

查询聚集函数结果

与查询构造器查询方法一样,可以使用聚集函数返回结果,常见的比如maxminavgsumcount

$count = App\Flight::where('active', 1)->count();
$max = App\Flight::where('active', 1)->max('price');

分页查询

分页查询可以直接使用paginate函数

LengthAwarePaginator paginate( 
    int $perPage = null, 
    array $columns = array('*'), 
    string $pageName = 'page', 
    int|null $page = null
)

参数说明

参数 类型 说明
perPage int 每页显示数量
columns array 查询的列名
pageName string 页码参数名称
page int 当前页码

返回值为 LengthAwarePaginator 对象。

$limit = 20;
$page = 1;
return Enterprise::paginate($limit, ['*'], 'page', $page);

插入

基本插入操作

插入新的数据只需要创建一个新的模型实例,然后设置模型属性,最后调用save方法即可

$flight = new Flight;
$flight->name = $request->name;
$flight->save();

在调用save方法的时候,会自动为created_atupdated_at字段设置时间戳,不需要手动指定

批量赋值插入

使用create方法可以执行批量为模型的属性赋值的插入操作,该方法将会返回新插入的模型,在执行create方法之前,需要先在模型中指定fillableguarded属性,用于防止不合法的属性赋值(例如避免用户传入的is_admin属性被误录入数据表)。

指定$fillable属性的目的是该属性指定的字段可以通过create方法插入,其它的字段将被过滤掉,类似于白名单,而$guarded则相反,类似于黑名单。

protected $fillable = ['name'];
// OR
protected $guarded = ['price'];

执行create操作就只有白名单或者黑名单之外的字段可以更新了

$flight = App\Flight::create(['name' => 'Flight 10']);

除了create方法,还有两外两个方法可以使用firstOrNewfirstOrCreate

firstOrCreate方法用来使用给定的列值对查询记录,如果查不到则插入新的。fristOrNewfirstOrCreate类似,不同在于如果不存在,它会返回一个新的模型对象,不过该模型是未经过持久化的,需要手动调用save方法持久化到数据库。

// 使用属性检索flight,如果不存在则创建...
$flight = App\Flight::firstOrCreate(['name' => 'Flight 10']);

// 使用属性检索flight,如果不存在则创建一个模型实例...
$flight = App\Flight::firstOrNew(['name' => 'Flight 10']);

更新

基本更新操作

方法save不仅可以要用来插入新的数据,也可以用来更新数据,只需先使用模型方法查询出要更新的数据,设置模型属性为新的值,然后再save就可以更新了,updated_at字段会自动更新。

$flight = App\Flight::find(1);
$flight->name = 'New Flight Name';
$flight->save();

也可使用update方法对多个结果进行更新

App\Flight::where('active', 1)
    ->where('destination', 'San Diego')
    ->update(['delayed' => 1]);

删除

基本删除操作

使用delete方法删除模型

$flight = App\Flight::find(1);
$flight->delete();

上述方法需要先查询出模型对象,然后再删除,也可以直接使用主键删除模型而不查询,使用destroy方法

App\Flight::destroy(1);
App\Flight::destroy([1, 2, 3]);
App\Flight::destroy(1, 2, 3);

使用约束条件删除,返回删除的行数

$deletedRows = App\Flight::where('active', 0)->delete();

软删除

软删除是在表中增加deleted_at字段,当删除记录的时候不会真实删除记录,而是设置该字段的时间戳,由Eloquent模型屏蔽已经设置该字段的数据。

要启用软删除,可以在模型中引用Illuminate\Database\Eloquent\SoftDeletes这个Trait,并且在dates属性中增加deleted_at字段。

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\SoftDeletes;

class Flight extends Model
{
    use SoftDeletes;

    /**
     * The attributes that should be mutated to dates.
     *
     * @var array
     */
    protected $dates = ['deleted_at'];
}

要判断一个模型是否被软删除了的话,可以使用trashed方法

if ($flight->trashed()) {
    //
}

查询软删除的模型

包含软删除的模型

如果模型被软删除了,普通查询是不会查询到该结果的,可以使用withTrashed方法强制返回软删除的结果

$flights = App\Flight::withTrashed()
      ->where('account_id', 1)
      ->get();

// 关联操作中也可以使用
$flight->history()->withTrashed()->get();
只查询软删除的模型
$flights = App\Flight::onlyTrashed()
      ->where('airline_id', 1)
      ->get();
还原软删除的模型

查询到软删除的模型实例之后,调用restore方法还原

$flight->restore();

也可以在查询中使用

App\Flight::withTrashed()
    ->where('airline_id', 1)
    ->restore();

// 关联操作中也可以使用
$flight->history()->restore();
强制删除(持久化删除)
// Force deleting a single model instance...
$flight->forceDelete();

// Force deleting all related models...
$flight->history()->forceDelete();

上述操作后,数据会被真实删除。


参考:

跟我一起学Laravel-数据库操作和查询构造器

在Laravel中执行数据库操作有两种方式,一种是使用\DB外观对象的静态方法直接执行sql查询,另外一种是使用Model类的静态方法(实际上也是Facade的实现,使用静态访问方式访问Model的方法,内部采用了__callStatic魔术方法代理了对成员方法的访问。

Continue reading →

PHP扩展开发(五)哈希表和数组API

Zend Hash API是以zend_hash_*样式的函数定义,注意的是,这里的zend_hash_*并不是函数,
而是宏定义,对应的函数一般为_zend_hash_*,哈希表相关操作源文件在 zend_hash.h/zend_hash.c 中。

哈希表结构

struct _hashtable;

typedef struct bucket {
    ulong h;            // 对char *key进行hash后的值,或者是用户指定的数字索引值
    uint nKeyLength;    // hash关键字的长度,如果数组索引为数字,此值为0
    void *pData;        // 指向value,一般是用户数据的副本,如果是指针数据,则指向pDataPtr
    void *pDataPtr;     //如果是指针数据,此值会指向真正的value,同时上面pData会指向此值
    struct bucket *pListNext;   // 整个hash表的下一元素
    struct bucket *pListLast;   // 整个哈希表该元素的上一个元素
    struct bucket *pNext;       // 存放在同一个hash Bucket内的下一个元素
    struct bucket *pLast;       // 同一个哈希bucket的上一个元素
    // 保存当前值所对于的key字符串,这个字段只能定义在最后,实现变长结构体
    char arKey[1];
} Bucket;

typedef struct _hashtable {
    uint nTableSize;        // hash Bucket的大小,最小为8,以2x增长。
    uint nTableMask;        // nTableSize-1 , 索引取值的优化
    uint nNumOfElements;    // hash Bucket中当前存在的元素个数,count()函数会直接返回此值
    ulong nNextFreeElement; // 下一个数字索引的位置
    Bucket *pInternalPointer;   // 当前遍历的指针(foreach比for快的原因之一)
    Bucket *pListHead;          // 存储数组头元素指针
    Bucket *pListTail;          // 存储数组尾元素指针
    Bucket **arBuckets;         // 存储hash数组
    dtor_func_t pDestructor;    // 在删除元素时执行的回调函数,用于资源的释放
    zend_bool persistent;       //指出了Bucket内存分配的方式。如果persisient为TRUE,则使用操作系统本身的内存分配函数为Bucket分配内存,否则使用PHP的内存分配函数。
    unsigned char nApplyCount; // 标记当前hash Bucket被递归访问的次数(防止多次递归)
    zend_bool bApplyProtection;// 标记当前hash桶允许不允许多次访问,不允许时,最多只能递归3次
#if ZEND_DEBUG
    int inconsistent;
#endif
} HashTable;

哈希表操作API

哈希表创建

int zend_hash_init(
    HashTable *ht,              /* 声明的HashTable变量指针 */
    uint nSize,                 /* 哈希表可能存储的最大元素数量 */
    hash_func_t pHashFunction,  /* 使用的哈希函数,现在一律使用NULL(DJBX33A) */
    dtor_func_t pDestructor,    /* 从哈希表移除元素时的回调函数 */
    zend_bool persistent        /* 该哈希表是持久化的还是每请求的 */
)

其中,nSize参数要为实际可能存储的元素数,如果超过该数目,将重新扩展哈希表为2倍大小。nSize
应该为2的整数倍,如果不是的话,将会自动设置为下一个2的整数倍数。

nSize取值: nSize = pow(2, ceil(log(nSize, 2)));

这里的pDestructor 参数是一个函数指针,该函数会在从哈希表移除元素的时候调用,比如zend_hash_del
zend_hash_update, 该函数的原型必须为:

void method_name(void *pElement); /* pElement为要移除的元素 */

另外,最后一个参数persistent如果设置为持久化的话,该哈希表变量ht必须是使用pemalloc()分配内存的。

例如,在每个PHP请求开始的时候,都会对EG(symbol_table)全局符号表进行初始化,这时会调用该函数:

zend_hash_init(&EG(symbol_table), 50, NULL, ZVAL_PTR_DTOR, 0);

这里的nSize为50,因此会被自动扩展为64。

哈希表填充

对哈希表的填充操作,主要有四个函数:

int zend_hash_add(
  HashTable *ht,        /* 要操作的哈希表指针 */
  char *arKey,          /* 数组的Key,这里是字符型key */
  uint nKeyLen,         /* 数组Key长度 */
  void **pData,         /* 实际存储的数据 */
  uint nDataSize,       /* 数据大小 */
  void *pDest           /* 如果指定,则为指向data的副本的指针 */
);
int zend_hash_update(HashTable *ht, char *arKey, uint nKeyLen,
                void *pData, uint nDataSize, void **pDest);

int zend_hash_index_update(
  HashTable *ht,
  ulong h, /* 数组下标索引 */
  void *pData,
  uint nDataSize,
  void **pDest
);

/* 该函数自动计算下一个索引,不需要自己提供 */
int zend_hash_next_index_insert(
  HashTable *ht,
  void *pData, uint nDataSize, void **pDest);

这里需要注意的是,前两个函数是对非数字key的数组操作的,后两个是对数值索引数组操作的。

zend_hash_addzend_hash_update的区别在于,一个是新增元素,一个是更新元素,如果arKey
已经存在了的话,zend_hash_add将会失败。

/* $foo['bar'] = 'baz'; */
zend_hash_add(fooHashTbl, "bar", sizeof("bar"), &barZval, sizeof(zval*), NULL);

使用zend_hash_index_update() 的例子:

ulong nextid = zend_hash_next_free_element(ht);
zend_hash_index_update(ht, nextid, &data, sizeof(data), NULL);

哈希表查找

由于哈希表有两种使用方式(数值索引/关联索引),因此,对于哈希表查找,也有两种查找函数:

int zend_hash_find(HashTable *ht, char *arKey, uint nKeyLength,
                                        void **pData);
int zend_hash_index_find(HashTable *ht, ulong h, void **pData);

例如:

void hash_sample(HashTable *ht, sample_data *data1)
{
   sample_data *data2;
   ulong targetID = zend_hash_next_free_element(ht);
   if (zend_hash_index_update(ht, targetID,
           data1, sizeof(sample_data), NULL) == FAILURE) {
       /* Should never happen */
       return;
   }
   if(zend_hash_index_find(ht, targetID, (void **)&data2) == FAILURE) {
       /* Very unlikely since we just added this element */
       return;
   }
   /* data1 != data2, 但是 *data1 == *data2 */
}

相比查找数组中的值,通常,我们还会经常用到判断数组中是否存在某个索引,这时,使用下面两个函数:

int zend_hash_exists(HashTable *ht, char *arKey, uint nKeyLen);
int zend_hash_index_exists(HashTable *ht, ulong h);

例如:

/* 该部分代码实现功能与isset($foo)类似 */
if (zend_hash_exists(EG(active_symbol_table),
                                "foo", sizeof("foo"))) {
    /* $foo is set */
} else {
    /* $foo does not exist */
}

快速填充和查找

要实现快速的填充和查找,这里采用的方法是首先使用zend_get_hash_value()函数计算出哈希索引值,
在接下来对数组的操作中,直接使用quick系列函数,避免每次操作都重新计算哈希值。

ZEND_API ulong zend_get_hash_value(const char *arKey, uint nKeyLength);

快速操作函数如下:

int zend_hash_quick_add(HashTable *ht,
    char *arKey, uint nKeyLen, ulong hashval,
    void *pData, uint nDataSize, void **pDest);

int zend_hash_quick_update(HashTable *ht,
    char *arKey, uint nKeyLen, ulong hashval,
    void *pData, uint nDataSize, void **pDest);

int zend_hash_quick_find(HashTable *ht,

    char *arKey, uint nKeyLen, ulong hashval, void **pData);
int zend_hash_quick_exists(HashTable *ht,
    char *arKey, uint nKeyLen, ulong hashval);

int zend_hash_quick_del(HashTable *ht, char *arKey, unit nKeyLength, ulong hashval);

例如:

void php_sample_hash_copy(HashTable *hta, HashTable *htb,
                    char *arKey, uint nKeyLen TSRMLS_DC)
{
    /* 事先计算出key的哈希值 */
    ulong hashval = zend_get_hash_value(arKey, nKeyLen);
    zval **copyval;

    if (zend_hash_quick_find(hta, arKey, nKeyLen,
                hashval, (void**)&copyval) == FAILURE) {
        /* arKey doesn't actually exist */
        return;
    }
    /* The zval* is about to be owned by another hash table */
    (*copyval)->refcount++;
    zend_hash_quick_update(htb, arKey, nKeyLen, hashval,
                copyval, sizeof(zval*), NULL);
}

zval* 数组API

在PHP扩展中,对哈希表的操作中95%的操作都是对用户空间的数据进行存取。因此PHP创建了一系列简单的
宏和助手函数用于对数组进行操作。

数组创建

int array_init(zval *arg);

该函数原型实际上是zend API定义的一个宏,其实现代码如下所示:

/* zend_API.h:347 */
#define array_init(arg)         _array_init((arg), 0 ZEND_FILE_LINE_CC)

/* zend_API.c:958 */
ZEND_API int _array_init(zval *arg, uint size ZEND_FILE_LINE_DC) /* {{{ */
{
    ALLOC_HASHTABLE_REL(Z_ARRVAL_P(arg)); /* 首先分配一个哈希表 */

    /* 调用zend_hash_init完成哈希表的初始化 */
    _zend_hash_init(Z_ARRVAL_P(arg), size, NULL, ZVAL_PTR_DTOR, 0 ZEND_FILE_LINE_RELAY_CC);
    Z_TYPE_P(arg) = IS_ARRAY;/* 设置变量的数据类型为数组 */
    return SUCCESS;
}

使用范例:

PHP_FUNCTION(sample_array)
{
    array_init(return_value);
}

数组填充

对与关联数组,提供了如下API:

int add_assoc_long(zval *arg,  const char *key, long lval);
int add_assoc_null(zval *arg,  const char *key);
int add_assoc_bool(zval *arg,  const char *key, zend_bool bval);
int add_assoc_resource(zval *arg,  const char *key, int r);
int add_assoc_double(zval *arg,  const char *key, double dval);
int add_assoc_string(zval *arg,  const char *key, char *strval, int dup);
int add_assoc_stringl(zval *arg,  const char *key, char *strval, uint strlen, int dup);
int add_assoc_zval(zval *arg,  const char *key, zval *value);

注意: 上述API为宏定义,为了直观展示,用函数定义的形式展现。

对于数值索引数组,提供了如下API,这些API都是函数定义:

ZEND_API int add_index_long(zval *arg, ulong idx, long n);
ZEND_API int add_index_null(zval *arg, ulong idx);
ZEND_API int add_index_bool(zval *arg, ulong idx, int b);
ZEND_API int add_index_resource(zval *arg, ulong idx, int r);
ZEND_API int add_index_double(zval *arg, ulong idx, double d);
ZEND_API int add_index_string(zval *arg, ulong idx, const char *str, int duplicate);
ZEND_API int add_index_stringl(zval *arg, ulong idx, const char *str, uint length, int duplicate);
ZEND_API int add_index_zval(zval *arg, ulong index, zval *value);

注意: Zend提供的数组API函数并不仅仅只有这些,还有更多方便实用的API请查看源文件: zend_API.h 346-431行。

范例:

PHP_FUNCTION(sample_array)
{
    zval *subarray;

    array_init(return_value);

    /* Add some scalars */
    add_assoc_long(return_value, "life", 42);
    add_index_bool(return_value, 123, 1);
    add_next_index_double(return_value, 3.1415926535);

    /* Toss in a static string, dup'd by PHP */
    add_next_index_string(return_value, "Foo", 1);

    /* Now a manually dup'd string */
    add_next_index_string(return_value, estrdup("Bar"), 0);

    /* Create a subarray */
    MAKE_STD_ZVAL(subarray);
    array_init(subarray);

    /* Populate it with some numbers */
    add_next_index_long(subarray, 1);
    add_next_index_long(subarray, 20);
    add_next_index_long(subarray, 300);

    /* Place the subarray in the parent */
    add_index_zval(return_value, 444, subarray);
}

上述代码片段创建的数组var_dump之后如下:

array(6) {
  ["life"]=> int(42)
  [123]=> bool(true)
  [124]=> float(3.1415926535)
  [125]=> string(3) "Foo"
  [126]=> string(3) "Bar"
  [444]=> array(3) {

    [0]=> int(1)
    [1]=> int(20)
    [2]=> int(300)
  }
}
Scroll Up