README

Eloquent-FileMaker是一个PHP包，用于Laravel，以便通过FileMaker数据API更轻松地与FileMaker数据库交互。该项目目标是提供与通过数据API处理FileMaker记录的接口尽可能相似，就像在原生Laravel中处理MySQL一样。

此包允许您通过数据API轻松连接到您的FileMaker数据库，并将记录数据作为Laravel模型获取，尽可能支持原生功能。

支持

此包由Gearbox Solutions构建和维护。我们使用Laravel、Vue、React和Node等技术构建出色的Web应用程序。如果您需要帮助构建自己的Web应用程序，无论是使用此包还是其他项目，请联系我们进行免费咨询，讨论您的项目。

特性

• 使用FileMaker数据API访问您的FileMaker数据
• 支持通过多个文件或使用多个凭证访问
• FMModel类
  • 扩展基础Model类，允许与许多标准模型功能兼容
  • 关系支持
  • 容器数据的读写
  • 自动名称/布局/表解析
  • 门户数据的读写
  • FileMaker -> Laravel字段名重映射
• 自动身份验证和会话管理
• Eloquent查询构建器和基础查询构建器
• 原始连接服务，易于数据API访问
• FileMaker数据库连接驱动程序
• 运行脚本
• 更多！

支持的Laravel版本

我们支持当前支持的Laravel版本。Laravel的早期版本可能兼容，但如果需要不兼容的更改，未来可能会被弃用。

2.0版的新功能

• 增加了对Laravel 11的支持
• FileMaker中的空字段默认返回null而不是空字符串
• FileMaker会话仅持续单个Laravel请求的持续时间，而不是默认情况下重复使用15分钟 - 这可以在配置中更改
• 对whereNot逻辑和实现的改进，使其行为更接近预期

从1.x升级到2.x

运行composer require gearbox-solutions/eloquent-filemaker:^2.0以升级到最新版本的包。

代码中的潜在更改

包的使用方式总体上保持不变。但是，有一些更改可能会影响您的代码。阅读下面的更改，了解在升级时可能需要哪些重构。

主要 - 空字段的更改

在版本1.0中，FileMaker中的空字段返回为空字符串。在版本2.0中，空字段返回为null。此更改使处理FileMaker数据更接近Laravel开发人员从数据库期望的行为。

如果您希望继续使用旧的行为，可以将 empty_strings_to_null 配置值更改为 false 以保留空字符串。否则，如果您有任何依赖于返回空字符串的空字段的代码，您可能需要重构代码以适应新的行为。

小改 - 改进了 whereNot 逻辑

在某些情况下，whereNot 可能会返回可能不正确或不符合预期的结果。这已在 2.0 版本中修复。如果您有依赖于旧的不正确行为的 whereNot 的代码，您可能需要重构代码以适应新的纠正行为。

安装

使用 Composer 在您的项目中安装 gearbox-solutions/eloquent-filemaker。

composer require gearbox-solutions/eloquent-filemaker

用法

安装此包后，您现在可以访问此包的所有功能。有几个不同的配置区域。

数据库配置

首先要做的是在您的 database.php 配置文件中添加一个新的数据连接。您在这里指定的连接将用于您的 FMModel 类中，以配置每个模型将连接到哪个数据库。

以下代码块可以作为模板使用，其中包含一些良好的默认设置。

'filemaker' => [
    'driver' => 'filemaker',
    'host' => env('DB_HOST', 'fms.mycompany.com'),
    'database' => env('DB_DATABASE', 'MyFileName'),
    'username' => env('DB_USERNAME', 'myusername'),
    'password' => env('DB_PASSWORD', ''),
    'prefix' => env('DB_PREFIX', ''),
    'version' => env('DB_VERSION', 'vLatest'),
    'protocol' => env('DB_PROTOCOL', 'https'),
    'cache_session_token' => env('DB_CACHE_SESSION_TOKEN', true), // set to false to log out after each reqeust. This can be slower than re-using a session token, but allows for globals to be set for individual user values.
    'empty_strings_to_null' => env('DB_EMPTY_STRINGS_TO_NULL', true), // set to false to return empty strings instead of null values when fields are empty in FileMaker
]

您应该为要连接到的每个 FileMaker 数据库添加一个数据库连接配置。每个文件可以有不同的配置，甚至可以位于不同的服务器上。

如果 cache_session_token 为 true，登录会话将按连接方式维护，并且将自动使用您为 Laravel 应用设置的任何缓存配置缓存令牌。这可以防止每个请求都需要重新登录到 Data API，这可以显著提高性能。如果您已为 Laravel 应用配置了缓存，您通常应将其设置为 true。

前缀

前缀配置选项将前缀添加到您指定的每个布局/表名称中。您不需要指定前缀，但这样做可能非常方便。

创建专门供 Data API 使用的布局，而不是使用您的常规 GUI 或开发者布局，这是一个好的做法。这些布局可能速度较慢，并且包含不必要的字段。为您的网络应用程序创建专门的布局，可以使您优化 Data API 的使用，并最大限度地提高网络应用程序的性能。考虑到这一点，管理这些布局的一种简单方法是将它们组织在一起在一个文件夹中，并给它们一个前缀，这样您就可以知道它们是用来做什么的。

例如，假设您有三个表 - 组织、联系人和发票。您可能希望为您的网络应用程序创建布局，例如 "dapi-organizations"、"dapi-contacts" 和 "dapi-invoices"。如果您将它们所有前缀设置为相同的文本，您可以设置前缀值，这样您就可以在 Laravel 中将它们称为 "organizations"、"contacts" 和 "invoices"。如果您正确地命名了模型类，遵循 Laravel 的命名指南，您甚至可以使布局自动解析，而无需手动输入！

Laravel 缓存配置

Eloquent FileMaker 将使用您的应用的缓存来缓存请求之间的 FileMaker Data API 会话令牌。为此，您需要确保您没有使用您的 FileMaker 连接作为缓存驱动程序。

Laravel 的默认设置是使用 database 缓存驱动程序。如果您的 FileMaker 数据库连接也是您的默认驱动程序，您需要更改您的缓存配置为其他内容，例如 file 或 redis。您可以在您的 .env 文件中更改缓存驱动程序。

Laravel 11

cache_store=file

Laravel 10 及更早版本

cache_driver=file

模型类

创建模型类是访问 FileMaker 数据的最简单方法，也是最具 Laravel 风格的方法。创建一个新的模型类，并将扩展类从 Model 更改为 FMModel。此类更改使您能够使用此包的功能与您的模型一起使用。

工作正常的事

FMModel 类扩展了 Laravel 的基础 Model 类，并且可以非常相似地使用。它支持许多标准 Eloquent 查询构建器功能，用于处理数据，如 where()、find()、id()、orderBy()、delete()、save() 等！

支持模型功能，如访问器和修改器，以及自动的表/布局名称解析、事件触发、观察者、belongsTo、hasOne 和 hasMany 关联、序列化（包含受保护属性等），以及我们可以确保兼容的其他许多功能。

我们的目标是能够使用任何有意义的 Eloquent 功能，因此这个包将尽可能支持更多。如果你认为有某些不支持的功能，请提交一个 pull 请求或通知我们。

请务必阅读 Laravel 的 Eloquent 文档，以了解 Eloquent 模型类可以做什么。

不工作的事

由于这个类扩展了 Model，IDE 中可能显示所有常规 eloquent 方法可用，但有些在 FileMaker 的数据 API 上下文中没有意义，因此不起作用。这些例子包括批量更新或原始 SQL 查询。

设置布局

针对您的 FileMaker 数据库的查询需要您从特定布局获取数据。Eloquent-FileMaker 支持 Laravel 的名称猜测功能，但如果有不匹配的情况，您可以通过在模型类上设置 $layout 属性来指定要用于模型的布局名称。

protected $layout = 'MyLayout';

空值和空字符串

对于开发者来说，null 是数据库操作中一个重要且期望的可能值。不幸的是，FileMaker 作为平台，没有 null 值的概念。未写入值的字段将包含一个空字符串。为了使这种行为更适合网络开发者，Eloquent FileMaker 在从数据 API 读取数据时自动将 FileMaker 字段的 '' 值转换为 null。

如果您希望将空的 FileMaker 字段返回为空字符串，可以在连接配置中将 empty_strings_to_null 配置值设置为 false。

Eloquent FileMaker 在将数据写回 FileMaker 数据库时，将始终自动将 null 值转换为 ''，以防止错误。

只读字段

您的 FileMaker 数据库中的许多字段将是只读的，例如摘要和计算字段，尽管在从数据库检索数据时您仍然希望获取它们。FMModel 将尝试将所有修改后的属性写回到 FileMaker 数据库。如果您尝试写入只读字段，例如计算字段，则在尝试将字段写回 FileMaker 数据库时将收到错误。

容器字段

此包支持读取和写入容器字段数据。容器字段作为模型上的属性检索自 FileMaker，其中包含可以用于从容器检索文件的 URL。

请注意：FileMaker 数据 API 不允许您在相关记录中写入容器字段

FileMaker 数据 API 容器字段文档

容器字段必须是指定布局的表 occurrences 中的一个字段。它不能是相关表中的容器字段。

写入容器字段

在设置容器字段时，应将值设置为 Illuminate/HTTP/File 或 Illuminate/HTTP/UploadedFile 对象。这些属性将在调用模型对象的 save() 方法时与其他模型更新一起写回到容器字段。

$file = new File(storage_path('app/public/gator.jpg'));
$newPet->photo = $file;
$newPet->save();

在将文件插入容器时自定义文件名

默认情况下，文件通过插入文件的文件名插入到容器中。如果您希望在将文件插入容器时设置新文件名，可以在设置容器时通过数组一起传递文件和文件名来实现。

$file = new File(storage_path('app/public/gator.jpg'));
$newPet->photo = [$file, 'fluffy.jpg'];
$newPet->save();

重命名和映射 FileMaker 字段

有时您可能正在使用具有不便的字段名的 FileMaker 数据库。可以通过设置 $fieldMapping 属性将这些字段重新映射到模型属性。这应该是一个字符串数组，将 FileMaker 字段名映射到新属性名。然后，您可以使用这些名称作为常规 Eloquent 属性，并且它们将与 FileMaker 中的正确字段一起工作。

protected $fieldMapping = [
  'My Inconveniently Named Field' => 'a_much_better_name'
];

然后您可以通过...来获取/设置属性

$myModel->a_much_better_name = 'my new value';

相关记录的字段

如果您通过数据 API 布局的关联在字段中包含相关记录，您需要添加一个 $fieldMapping 属性才能访问您的相关数据。

例如，如果您有一个与拥有第一辆车的关系一对一的 Person 表

protected $fieldMapping = [
  'person_CARfirst::color' => 'first_car_color',
  'person_CARfirst::make' => 'first_car_make',
  'person_CARfirst::model' => 'first_car_model'
];

相关数据可以像模型的其他任何属性一样获取/设置。数据将从第一个相关记录读取并写回。

$personFirstCarColor = $person->first_car_color;

门户数据

可以根据 FileMaker 布局上门户的对象名称作为属性访问门户数据。可以使用字段名称的数组键来访问字段。

例如，如果您有一个基于 "person_PET" 关系的 "person_pet_portal" 对象名称的布局上的门户，您可以通过该属性的数组来访问您的门户数据

// Get the name of the first related Pet
$firstPetName = $person->person_pet_portal[0]['person_PET::name'];

您可以以相同的方式将数据写回门户

// Set the 'type' of the second related pet in the portal
$person->person_pet_portal[1]['person_PET::type'] = 'cat';

转换 FileMaker 时间戳和日期字段

此包为您提供了特殊的处理，将 FileMaker 时间戳和日期字段转换为 Carbon 实例。要利用此功能，您必须像使用原生 Laravel 模型类一样映射字段。您可以使用与这些属性相同的 $casts 属性。

protected $casts = [
    'nextAppointment' => 'datetime',
    'birthday' => 'date',
];

写入 FileMaker 的日期和时间戳字段的格式可以通过模型中 $dateFormat 属性来更改。此值必须与 FileMaker 数据 API 输出的时间戳值格式兼容，并将写入到您的数据库中。一个重要的要求是这必须是一个完整的日期时间格式，而不仅仅是日期格式。

以下是一些示例格式

protected $dateFormat = 'n/j/Y g:i:s A'; // 7/1/1920 4:01:01 PM
protected $dateFormat = 'n/j/Y G:i:s'; // 7/1/1920 16:01:01

示例 FMModel 类

// Person.php

class Person extends FMModel
{

    protected $layout = "person";

    protected $fieldMapping = [
        'first name' => 'nameFirst',
        'last name' => 'nameLast'
    ];

    protected $casts = [
        'birthday' => 'date',
    ];


    public function pets(){
        return $this->hasMany(Pet::class);
    }

}

基本查询构建器和 FM 门面

类似于本地的 DB 门面，您可以使用 FM 门面生成和执行查询，而无需通过模型。这对于使用非基于表的 Data API 功能特别有用，例如设置全局变量或执行脚本，尽管您也可以使用它来检索记录。虽然 FMModel 和它使用的 Eloquent 查询构建器将返回组织良好的 FMModel 集合，但基本查询构建器将返回来自 FileMaker 数据 API 的直接响应。

FM 门面提供了对 FMBaseQueryBuilder 类的访问，该类也被 FMModel 对象使用的 Eloquent Builder 所使用。FMBaseQueryBuilder 的方法也对 FMModel Eloquent 查询构建器可用。

在安装此包之后，DB 门面仍可用于针对 FileMaker 数据库进行查询，例如基本记录查询 DB::table('pets')->where('name', 'Cosmo')->first()，但 FM 门面允许您访问更多 FileMaker 特定的功能，并且通常应替换 DB 用于访问您的 FileMaker 数据。

与 FMModel 类和 Eloquent 查询构建器一样，目标是支持与 DB 门面相同的功能集，因此请查看 Laravel 查询构建器文档 了解基本查询构建器功能。

FileMaker查询构建器和FM Facade中的FileMaker特定功能

除了基本的查询构建器功能外，通过FM Facade或FMModel优雅构建器访问的FMBaseQueryBuilder类还提供了许多新的FileMaker特定方法。

FileMaker数据API支持在请求中设置多个参数，以执行运行脚本和在不同时间传递参数等活动。请查阅FileMaker数据API指南以及更具体的《数据API参考文档》以查看每个特定调用支持哪些选项。

可以通过遵循API指南中的说明在运行的FileMaker服务器上查看数据API参考文档。

一般来说

“要在远程FileMaker服务器上查看参考，请打开浏览器并输入URL https://host/fmi/data/apidoc/，其中host是运行FileMaker服务器的主机的IP地址或主机名。”

以下是一系列允许您为数据API功能设置参数的方法。请注意，其中大部分可以像标准查询构建器一样进行链式调用。

从以下开始

FM::table()
FM::connection()
FM::layout() // alias for table()
FM::setGlobalFields() // not chainable

可链式调用

// standard query-builder stuff like where, orderBy, etc.
->limit( $value )
->offset( $value )
->script( $scriptName, $param)
->scriptParam( $param )
->scriptPresort( $scriptName, $param
->scriptPresortParam( $param )
->scriptPrerequest( $scriptName, $param )
->scriptPrerequestParam( $param )
->layoutResponse( $layoutName )
->portal( $portalName )
->portalLimit( $portalName, $limit )
->portalOffset( $portalName, $startingRecord  )
->sort() // alias for the native orderBy()
->omit()
->fieldData( $array )
->portalData( $array )

最终链式链接方法

// standard query-builder stuff like get, first, etc.
->findByRecordId()
->performScript()
->setContainer()
->duplicate()
->createRecord()
->getLayoutMetadata()

示例

查找名为Jaina的人

$person = FM::table('person')->where('nameFirst', 'Jaina')->first();

查找客户的10个最新发票

$invoices = FM::layout('invoice')->where('customer_id', $customer->id)->orderByDesc('date')->limit(10)->get();

获取布局元数据，包括字段、端口和值列表信息

$layoutMetadata = FM::getLayoutMetadata('MyLayoutName');

获取特定记录的布局元数据

$layoutMetadata = FM::layout('MyLayoutName')->recordId(879)->getLayoutMetadata();

运行脚本

$result = FM::layout('MyLayoutName')->performScript('MyScriptName');

使用JSON数据作为参数运行脚本

$json = json_encode ([
    'name' => 'Joe Smith',
    'birthday' => '1/1/1970'
    'favorite_color' => 'blue'
]);

$result = FM::layout('globals')->performScript('New Contact Request'; $json);

在非默认数据库连接上执行脚本

$result = FM::connection('MyOtherDatabaseConnectionName')->layout('MyLayoutName')->performScript('MyScriptName');

使用数组形式的字段数据创建记录，然后在同一请求中创建记录后执行脚本

FM::layout('MyLayoutName')->script('ScriptName')->fieldData($data)->createRecord();

设置全局字段。全局字段需要使用完整的table_name::field_name语法。

        $globalFields = [
            'GLOB::my_global_field' => 'New global value',
            'GLOB::other_global_field' => 'New global value',

        ];
        FM::setGlobalFields($globalFields);

注销、断开连接并结束您的数据API会话

Eloquent-FileMaker会尝试通过在请求之间缓存会话令牌来自动重用会话令牌。这意味着您将在FileMaker服务器管理控制台中看到会话保持打开。它将根据您的服务器或数据库的断开连接设置自动断开。

如果您想手动注销并结束会话，您可以通过FM Facade或通过模型来这样做。

FM::connection()->disconnect();

或者

MyModel::getConnectionResolver()->connection()->disconnect();

将原生Laravel模型与FMModels相关联

可以将来自MySQL数据库的原生Laravel Model对象与来自FileMaker数据库的FMModels之间的关联。为此，您需要在database.config文件中设置这两个连接，并确保您的模型通过在Model和FMModel类中设置$connection属性指向正确的连接。

protected $connection = 'theConnectionName';

一旦设置正确的连接，FMModel对象到基于SQL的Model对象的关联应该可以自动正确解决。对于版本大于2.3.0的常规Model对象到FMModel对象的关联（需要添加新的特质以启用关联创建）。对于版本低于2.3.0或需要更多关系控制的，可以使用以下示例手动添加关系连接。

您可以通过手动创建新的eloquent-filemaker belongsTo对象或导入新的特质并设置适当的键来创建关系，如belongsTo。

使用特质创建关系（2.3.0+）

HasHybridRelationships特质允许模型自动解决从Model到FMModel的关联。以下是一个使用特质创建SQL数据库中的原生Laravel User Model和基于FileMaker的Company FMModel类的示例。

// User.php

use GearboxSolutions\EloquentFileMaker\Database\Eloquent\Concerns\HasHybridRelationships;

class User extends Model
{
    use HasHybridRelationships;
    
    public function company()
    {
        // The Company class is an FMModel and is stored in FileMaker
        // The correct relationship will be resolved automatically thanks to the HasHybridRelationships trait
        return $this->belongsTo(Company::class, 'company_id', 'id');
    }
}

创建了这种关系后，我们可以像在单个数据库中一样获取User所属的FMModel的Company。

// set $company to a FMModel of the User's Company
$company = $user->company;

手动创建关系

使用HasHybridRelationships特质是创建原生 Laravel 模型和 FMModels 之间关系的最简单方法。然而，如果您正在使用 Eloquent FileMaker 的旧版本或希望手动管理关系，您可以通过使用 Eloquent FileMaker 版本的关系类型来建立关系。每个有效的关系类型都将位于 \GearboxSolutions\EloquentFileMaker\Database\Eloquent\Relations\ 命名空间下。

以下是将原生 Laravel 用户模型设置为属于基于 FileMaker 的公司 FMModel 类的示例。

// User.php

class User extends Model
{
    public function company()
    {
        // The Company class is an FMModel and is stored in FileMaker
        return new \GearboxSolutions\EloquentFileMaker\Database\Eloquent\Relations\BelongsTo(Company::query(), $this, 'company_id', 'id', '');
    }
}

许可证

Eloquent-FileMaker 是开源软件，受 MIT 许可证的许可。