README

(M)agic (A)ccessors (A)nd (M)utators

通过自动生成来避免编写和测试无数个getter和setter的繁琐工作！

注意：仍在开发中。请自行承担风险等。

安装

唯一支持的安装方法是 Composer。实际上，Maam 需要 Composer 来施展其魔力！

composer require "michaelmoussa/maam:dev-master"

使用

初始化

将 Maam 添加到您的项目中非常简单。在启动应用程序时，只需添加以下几行

use Moose\Maam\Maam;

$loader = include '/path/to/vendor/autoload.php'; # Change this according to your application
$maam = new Maam(Maam::MODE_DEVELOPMENT);
$maam->init($loader);

首先，通过包含 vendor/autoload.php 脚本来获取 Composer 的 ClassLoader 实例。接下来，创建 Maam 初始化器的实例。最后，运行 ->init(...) 方法。

Maam 需要其他三个信息才能工作，它们是

• 您应用程序源代码的路径。
• 您希望 Maam 写入生成的代码的路径。
• 您 Composer 的 autoload.php 的路径

如果您没有指定这些路径，Maam 将使用合理的默认值，它们是

• 应用程序源代码：<maam-directory>/../../../src
  • 假设您有一个正常的 Composer 安装，这将是在您的项目根目录下的 src 目录。
• 生成路径：<maam-directory>/../../../cache/maam
  • 假设您有一个正常的 Composer 安装，这将是在您的项目根目录下的 cache/maam 目录。
  • 注意：此目录必须存在并且可写！
  • 注意： cache/maam/* (或您指定的任何内容) 应该在您的 .gitignore 中。
• Composer 的 autoload.php：<maam-directory>/../../autoload.php
  • 假设您有一个正常的 Composer 安装，这将是在 Maam 安装目录之上的两个目录中的 autoload.php。

这些默认值不适用于您的应用程序？没问题！在调用 ->init() 之前，使用 setApplicationAutoloadPath()、setApplicationSourcePath() 和/或 setGenerationPath() 方法来配置您自己的路径。

运行模式

Maam 有两种模式 - 开发和生产。生产是默认模式，您可以通过传递模式到构造函数或使用 ->setMode() 方法来覆盖此模式。

建议您根据脚本运行的 环境 初始化 Maam 时指定模式。例如，假设您有一个 APPLICATION_ENV 常量，告诉您的应用程序它在哪里运行，您可以这样做：

if (APPLICATION_ENV === 'development') {
    $maam = new Maam(Maam::MODE_DEVELOPMENT);
} else {
    $maam = new Maam(Maam::MODE_PRODUCTION);
}

MODE_DEVELOPMENT

此运行模式告诉 Maam 它正在开发环境中运行，其中源文件可能会经常更改。因此，每次初始化器运行时，它都会重新扫描和重新生成您的源文件。这可能会根据您的类和 Maam 注释的数量在您的本地开发环境中引起明显的减速。

有方法可以最小化执行此操作的开销，这些方法将在未来的库中实现。

MODE_PRODUCTION

这是当您的应用程序部署到生产服务器时应使用运行模式。这告诉Maam，您已经生成了新的源文件。当然，如果您还没有这样做，当运行应用程序时，它可能会遇到错误，或者表现不可预测。

手动生成新源文件很简单。

/path/to/vendor/bin/maam.php /path/to/src

Maam将生成您的源文件，并告知您它正在添加到类映射中。

这很简单，但现在已经不再是这样了。 :) 将会修复。请查看#12以了解状态。

注解

Maam通过使用注解工作，这些注解是您可以在phpDoc块中放置的特殊注释。Maam目前有三个注解 - @Getter、@Setter和@Both，这些注解表示您需要生成getter、setter或者两者都生成。让我们看看这个示例文件

<?php
// /path/to/my-application/src/MyApplication/Person.php

namespace MyApplication;

use Moose\Maam\Annotation as Maam;

class Person
{
    /**
     * @Maam\Getter
     */
    protected $firstName;

    /**
     * @Maam\Setter
     */
    protected $lastName;

    /**
     * @Maam\Both
     */
    protected $dateOfBirth;
}

在这个示例中，我们告诉Maam我们想要为firstName属性生成getter，为lastName属性生成setter，并且为dateOfBirth属性生成getter和setter。在运行maam.php之后，将生成此脚本

<?php
// /path/to/my-application/vendor/michaelmoussa/maam/generated/MyApplication/Person.php

namespace MyApplication;

use Moose\Maam\Annotation as Maam;

class Person
{
    /**
     * @Maam\Getter
     * @var string
     */
    protected $firstName;

    /**
     * @Maam\Setter
     */
    protected $lastName;

    /**
     * @Maam\Getter
     * @Maam\Setter
     */
    protected $dateOfBirth;

    /**
     * Sets the firstName.
     *
     * @param mixed $firstName
     * @return void
     */
    public function setFirstName($firstName)
    {
        $this->firstName = $firstName;
    }

    /**
     * Gets the lastName.
     *
     * @return mixed
     */
    public function getLastName()
    {
        return $this->lastName;
    }

    /**
     * Sets the dateOfBirth.
     *
     * @param mixed $dateOfBirth
     * @return void
     */
    public function setDateOfBirth($dateOfBirth)
    {
        $this->dateOfBirth = $dateOfBirth;
    }

    /**
     * Gets the dateOfBirth.
     *
     * @return mixed
     */
    public function getDateOfBirth()
    {
        return $this->dateOfBirth;
    }
}

生成了41行getter/setter代码，我们只需要几个注解！

错误 / 贡献

发现了错误？谢谢！请尽可能提供详细信息，以便我尽快解决。创建问题。

我的文档很糟糕吗？创建问题并告诉我您不理解的地方，我会尽力让它更清晰。

添加了酷炫的功能并想要发送Pull Request？请随意！只需确保为添加的任何内容包括单元测试，并遵守PSR2 PHP编码标准。