README

Numenor 是一个 PHP 实用类库，可用于任何简单项目作为独立模块，或与框架（包括自有或市场框架）一起使用。

动机

我承认这个库在阳光下并不代表什么新东西（我承认自己正经历严重的创造力危机），但这并不是我的目标。主要目标是添加一些我在大部分已工作的项目中发现是必需的，但市场框架不能快速直观提供的功能，也就是说，无需配置多个模块和注册服务在视图中或控制器中，或任何其他地方。

与框架一起工作真是太好了，我首先承认这一点。然而，有时可能会感到沮丧。例如，在 Symphony 项目中工作，我记得很难找到正确修改参数发送方法的方法。如果所有项目都有适当的文档，这将被解决，但... 我们的政治家们比要求当前开发条件下（大多数情况下价格低廉且期限紧迫）的项目有适当的文档更容易关心国家的福祉，而不是他们的政治生涯。

因此，我创建了此库。主要目标是提供市场框架认为过于琐碎而不予实现的特性（例如，执行时间计时器用于应用程序执行时间基准测试），但程序员可能会感到不愿单独作为模块实现，因为，嘿，完成巨大项目的最后期限远远早于投入时间以可重用方式创建这些功能所需的必要时间。在某些情况下，我创建了某些框架类的简单 适配器，因为重新发明轮子是开发领域的一个致命错误，但某些接口在原始形式中有些混乱或文档不完整（比如，Zend 框架 API 的文档就相当令人失望）。

谈到 Zend，只要可能，我就扩展了 Zend 2 框架的类。我这样做有两个原因

• 我比其他框架更熟悉 Zend；
• Zend 模块可以很容易地以 独立 模式使用，特别是当使用 Composer 时（每个用 PHP 开发的都应该使用 Composer 来管理项目的依赖项）；

正是因此，我认为这个库可以很容易地与使用任何市场框架的项目集成，甚至没有特定框架。我试图将配置操作集中在一个地方，这样开发者就可以使用 Numenor 的类，而无需修改太多现有代码（最好是只更改一行代码来包括和配置库以供使用）。这是指导这个库设计的原则，我不打算偏离这个原则。

文档纪律

本项目也是提高我对项目文档维护纪律的一种方式。从每个类的PHPDoc到对仓库提交的描述，甚至到维护这份文档，目标不仅是保持项目文档的良好状态（参考之前关于Zend Framework文档的投诉），还要为未来的项目创造不推迟文档的文化。你知道是这样的：那个匆忙创建的类，在编码热情中忘记添加文档注释，但我保证在下一个提交中它会存在……两百次提交后，类有了PHPDoc，无法使用PHPDocumentor正确生成文档，混乱和破坏，大众的歇斯底里...

文档很重要，大家。无论项目大小。有一次我花了两周时间重构了一个我在一家公司工作的整个类库，目的是让我的工作和同事的生活更轻松。这项努力并没有得到公司高层（即使大部分工作都是在下班时间完成的，没有成本——“我们是笨蛋，是的老板，但我们努力做对事情…”）的认可，但节省的时间很快就证明很有价值。不幸的是，2015年的危机紧接着就来了……从这一点开始，故事就变得悲伤了。

命名规范

对于Numenor库中使用的命名空间、类、属性、方法、变量名和对象/数组键，采用了以下规范

• 由于作者来自巴西，所以优先使用葡萄牙语名称，除非没有常见的翻译。例如，术语如bootstrap、cache和debug保持英文，因为它们的翻译并不常用（在bootstrap的情况下，我没有在字典中找到合适的翻译；《脱鞋》是一个有趣的建议，可能会被某个爱开玩笑的葡萄牙语程序员提出）。
• 尽可能让方法名称包含一个动词，表示方法正在执行的动作。
• 上述规则的例外是getter和setter方法，它们以get和set为前缀。这是在葡萄牙语中使用的标准。
• 我总是选择最能描述特定元素是什么或做什么的名称，而不是选择缩写。Douglas Crockford经常说，编程的大部分时间不是用来打字代码，而是用来查看代码，试图理解它的工作方式和出错原因。使用的名称越能自我解释，就越容易理解整个应用程序，并且在开发过程中花在令人沮丧和耗时的部分上的时间就越少。
• 另一方面，我尽量避免创建过于描述性的名称，除非创建新的异常类。异常是特殊情况，因为它们的名称应该有助于记录发生的错误。错误消息并不总是能够确切地说出发生的错误是什么（特别是当需要将异常作为友好的错误消息传达给用户时）。

PSR-2（版本2.1.3+）

从2.1.3版本开始，库的文件与PSR-2标准建议兼容。这当然不会影响库的功能，但它作为处理PHP最接受的标准代码的经验。而PHP需要一些标准来扎根，而不是变成一团糟。