README

PHP 操作工具集

首先：Underscore.php 并不是 直接 从 Underscore.js 搬运过来的 PHP 版本（好吧，我是认真的）。它并不是旨在直接搬运其方法，而是更多地搬运其哲学。

它是一个完全的 PHP 操作工具集，通过优雅的语法糖包裹，直接受到 Laravel 框架 的启发。著名的 __() 已被淘汰，取而代之的是旨在像句子一样阅读的方法和类名，例如： Arrays::from($article)->sortBy('author')->toJSON()。

它提供了针对各种类型（字符串、对象、数组、函数、整数等）的近一百种方法，并提供了一个解析类，有助于在途中从一种类型切换到另一种类型。哦，而且它还在不断增长。最好的部分？它巧妙地包装了原生 PHP 函数，意味着 String::replace 实际上是一个对 str_replace 的动态调用，但具有允许链式调用和一致的参数顺序的优势（Underscore 中的所有函数都将主题作为第一个参数，无论什么情况下）。

它既可以作为独立通过 Composer 安装，也可以作为 Laravel 框架的包。所以，你知道，你几乎没有任何借口。

安装 Underscore

要安装 Underscore.php，只需运行 composer require anahkiasen/underscore-php。请注意，Underscore 的类型类（数组、字符串等）默认在 Types 文件夹中命名空间，所以为了使用数组，你需要这样做

use Underscore\Types\Arrays;

使用 Underscore

它可以作为静态类和面向对象的类使用，所以以下两种用法都是有效的

$array = array(1, 2, 3);

// One-off calls to helpers
Arrays::each($array, function($value) { return $value * $value; }) // Square the array
Function::once($myFunction) // Only allow the function to be called once
Number::paddingLeft(5, 5) // Returns '00005'
Object::methods($myObject) // Return the object's methods
String::length('foobar') // Returns 6

// Or chain calls with the 'from' method
Arrays::from($array)->filter(...)->sort(...)->get(2)

// Which does this in the background
$array = new Arrays($array);
$array->filter(...)->sort(...)->get(2)

对于那些怀念旧的 __()，提供了一个通用的 Underscore 类，它可以遍历 Underscore.php 的所有方法。为此，它检查它知道的方法，并分析方法的主题（这意味着如果你执行 Underscore::contains('foobar', 'foo')，它知道你寻找的不是 Arrays::contains）。

关于类型：重要的是要注意，使用特定的类型类创建 Underscore 存储库将转换提供的主题的类型。比如说，你有一个对象，并且执行 new Arrays($myObject) – 这将把对象转换为数组，并允许你使用数组方法。为此，Underscore 使用其 Parse 类的方法，这些方法大部分只是类型转换并返回（例如这个 (array) $object），但它有时会走得更远以理解你想要做什么：如果你将数组转换为字符串，它将将其转换为 JSON，如果你将数组转换为整数，它将返回数组的大小，等等。

核心概念是这样的：静态调用从其方法返回值，而链式调用更新它们正在工作的对象的值。这意味着 Underscore 对象不会返回其值，直到你调用它上面的 ->obtain 方法——在此之前，你可以无限链式调用，它将保持为一个对象。例外的是某些被认为是 断链器 的属性，它们将返回对象的值。一个例子是 Arrays->get。

请注意，由于所有传递给Underscore的数据都被转换成对象，因此您可以进行这类操作，再加上链式方法的强大功能，这使数据处理变得非常容易。

$array = new Arrays(['foo' => 'bar']);

echo $array->foo // Returns 'bar'

$array->bis = 'ter'
$array->obtain() // Returns array('foo' => 'bar', 'bis' => 'ter')

自定义Underscore

Underscore.php提供扩展任何类的自定义函数的能力，所以尽情发挥吧。如果您认为您有一个任何人都可以享受的函数，请发起一个pull request，让大家都能享受它！

String::extend('summary', function($string) {
  return String::limitWords($string, 10, '... — click to read more');
});

String::from($article->content)->summary()->title()

您还可以在提供的配置文件中为Underscore的所有方法提供自定义别名。只需向aliases选项中添加条目，键为别名，值为指向的方法。

可扩展性

从面向对象的角度来看，Underscore.php的类也是可扩展的。您可以使用setSubject方法（或直接通过$this->subject =，前提是您在最后返回$this）更新Underscore仓库。创建Underscore仓库时，默认的主题是一个空字符串，您可以通过在getDefault方法中返回任何您想要的内容来更改它。

class Users extends Arrays
{
  public function getDefault()
  {
    return 'foobar';
  }

  public function getUsers()
  {
    // Fetch data from anywhere

    return $this->setSubject($myArrayOfUsers);
  }
}

$users = new Users; // Users holds 'foobar'
$users->getUsers()->sort('name')->clean()->toCSV()

// Same as above
Users::create()->getUsers()->sort('name')->clean()->toCSV()

重要的是不要对Underscore中存在的庞大方法集合和扩展一个类型可能造成的危险感到恐慌：方法不是包含在类本身中，而是在方法仓库中。因此，如果您扩展了String类，并想在您的类中有一个与String::length完全不同的意义的length方法，它不会引起任何签名冲突或任何其他问题。

此外，请注意Underscore方法路由是动态的，所以如果您的主题是数组，但在中途变成了字符串，Underscore总会找到正确的类来调用，不管您最初扩展了什么。不过，尽量跟踪您的主题：如果您的主题变成了字符串，例如调用->map将返回错误。

调用原生方法

Underscore原生地扩展了PHP，因此当上下文匹配时，它可以自动引用原始PHP函数。现在，PHP本身没有很多约定，所以Arrays::寻找array_函数，String::寻找str_以及一些其他硬编码的重定向，但仅此而已。显然，这允许在许多其他情况下进行链式调用，这些情况在其他情况下只能通过引用工作。

Arrays::diff($array, $array2, $array3) // Calls `array_diff`
Arrays::from($array)->diff($array2, $array3)->merge($array4) // Calls `array_diff` then `array_merge` on the result

文档

您可以在仓库的wiki或官方页面上找到所有类和方法的详细总结。变更日志可在CHANGELOG文件中找到。

关于Underscore.php

在GitHub上实际上还有一个Underscore.js到PHP的端口，在这里——我第一次发现它是用于Laravel 4的。我很快对代码的混乱、缺乏更新以及背后的1:1思维感到失望。

这个重制的Underscore.php不旨在成为Underscore.js的直接端口。它有时会省略与PHP开发者无关的方法，将其他方法重命名为更常见的术语，提供更丰富的语法，添加大量方法，并为未来添加方法留出空间——而之前的端口迅速将所有JS方法重编为PHP，然后就此结束。

如果您来自JavaScript并对其中的某些更改感到困惑，不要把所有责任都归咎于我试图搞乱一切。一个基本的例子是map函数：在PHP中，它具有完全不同的含义，因为存在一个array_map函数，它基本上做的是JS中__::invoke所做的。所以map现在是Arrays::each。始终记住，这是首先为PHP开发者制作的，两者之间确实存在差异，以适应PHP中的常见术语。