rjdeliveryomaha/courierinvoice

用于使用快递发票API的工具

维护者

详细信息

github.com/rjdeliveryomaha/courierinvoice

主页

源代码

问题

安装: 47

依赖项: 0

建议者: 0

安全: 0

星标: 0

关注者: 3

分支: 0

开放问题: 0

2.7.6 2024-05-24 19:30 UTC

Requires

Suggests

MIT ea24b3914c328eb56f8800e507de4d4d5c6054ff

  • Paul Pierce <paul.woop@rjdeliveryomaha.com>

courier invoice

This package is auto-updated.

Last update: 2024-09-24 23:36:28 UTC

README

一组用于快递发票API的类

安装

composer require "rjdeliveryomaha/courierinvoice"

或者，将 "rjdeliveryomaha/courierinvoice":"^2.0.0" 添加到 composer.json

类

extras

SecureSessionHandler

扩展PHP的 SessionHandler 类。

提供用于会话管理的静态函数。

出错时抛出异常。

在 $config 中可设置的属性

这些属性在 extras/includes 中有描述。

  • session_name

  • domain

  • lifetime

  • path

  • samesite

  • secure

  • alternateHijackingTest

公共方法

try {
  SecureSessionHandler::start_session($config);
} catch (Exception $e) {
  echo $e->getMessage();
  exit;
}

此函数将尝试使用 ini_set() 应用以下设置

如果这些设置失败，将抛出异常。

如果没有提供有效的会话名称，将抛出异常。

如果没有提供域名，将使用 $_SERVER['SERVER_NAME']。

如果 $config['alternateHijackingTest'] 设置为 false，用户的IP地址和用户代理将被存储在会话中，并在每次验证调用时与服务器提供的值进行比较。然而，不建议将该值设置为 true，但在用户IP地址因网络不稳定或服务提供商问题而频繁更改的情况下可能有必要。

$_SESSION['formKey'] 被设置为通过 bin2hex(random_bytes(32)) 生成的值。验证将在每次POST请求时将此值与 $_POST['formKey'] 进行比较，然后迭代值。如果这些值不匹配，将抛出带有消息 "Session Error" 的异常。

echo SecureSessionHandler::outputKey();

返回 $_SESSION['formKey'] 的当前值。

SecureSessionHandler::destroySession();

  • 清除会话值。

  • 保留 $_SESSION['formKey'] 的值。

  • 销毁当前会话。

  • 重新生成会话ID。

try {
  SecureSessionHandler::start_session($config);
} catch(Exception $e) {
  echo "<span data-value=\"error\">{$e->getMessage()}</span>";
  return FALSE;
}
echo SecureSessionHandler::outputKey();
return FALSE;

为 $_SESSION['formKey'] 设置并返回新值。

如果没有活动会话，将尝试创建一个。

CommonFunctions

一个用于整个项目中使用的函数的实用工具类。

出错时抛出异常。

用法

try {
  $functions = new CommonFunctions($config, $data);
} catch(Exception $e) {
  return $e->getMessage();
}

在 $data 中可设置的属性

  • noSession

    • 数字

    • 如果设置为等于 1，则类将不会尝试使用任何会话值。

公共方法

$functions->getProperty($property);

如果属性存在，则返回值。

如果属性不存在，则返回 false。

$functions->updateProperty($property, $value);

将属性设置为新的值。

在成功时返回 true。

如果属性不存在，则返回 false。

$functions->addToProperty($property, $value);

将 $value 添加到属性。

在成功时返回 true。

如果属性不存在，则返回 false。

如果 $value 或属性不是数字，则返回 false。

$functions->substractFromProperty($property, $value);

从属性中减去 $value。

在成功时返回 true。

如果属性不存在，则返回 false。

如果 $value 或属性不是数字，则返回 false。

$functions->compareProperties($obj1, $obj2, $property, $strict=FALSE);

如果属性在两个对象中都不存在，则返回 false。

如果属性具有相等的值，则返回 true。

$strict 比较类型和值。

如果属性具有相同的值，则返回 true。

$functions->debug();

以美观的方式打印属性和值。

$functions->getError();

返回最后错误。

Query

扩展 通用函数

此类处理创建和执行对 API 的调用。

出错时抛出异常。

用法

try {
  $query = new Query($config, $data);
} catch(Exception $e) {
  return $e->getMessage();
}

在 $data 中可设置的属性

  • primaryKey

    • 整数

    • 除非使用 PUT 或 DELETE，否则不应设置。

    • 如果使用 PUT 或 DELETE 方法，并且此属性未设置，则会抛出异常。

  • endPoint

    • 字符串

    • 有效端点

      config, tickets, invoices, clients, o_clients, contract_locations, contract_runs, schedule_override, drivers, dispatchers

  • method

    • 字符串

    • 有效值

      POST, PUT, GET, DELETE

  • queryParams

    • 关联数组

    • 键

      • 包含 / 排除

        索引数组，用于从端点检索 / 忽略资源。如果同时提供，则优先包含。如果省略，则返回所有资源。例如

        仅返回票号、已开票客户和票价。

        $data['queryParams']['include'] = [ 'TicketNumber', 'BillTo', 'TicketPrice' ];

        仅返回所有资源中的 除 提货国家之外的资源。

        $data['queryParams']['exclude'] = [ 'pCountry' ];

      • filter

        • 简单的 "and" 查询

          索引数组，包含关联数组。例如

          选择费用等于 5 且开票给除客户 1 之外客户的票。

          $data['queryParams']['filter'] = [];

$data['queryParams']['filter'][] = ['Resource'=>'Charge', 'Filter'=>'eq', 'Value'=>5];

$data['queryParams']['filter'][] = ['Resource'=>'BillTo', 'Filter'=>'neq', 'Value'=>1];

        • 复杂的 "and" 和 "or" 查询

          索引数组，包含简单的 "and" 查询。例如

          选择费用在 1 到 5 之间且开票给客户 1 或开票给客户 2 的票。

          $filter1 = [];

$filter1[] = ['Resource'=>'Charge', 'Filter'=>'bt', 'Value'=>'1,5'];

$filter1[] = ['Resource'=>'BillTo', 'Filter'=>'eq', 'Value'=>1];

$filter2 = [ ['Resource'=>'BillTo', 'Filter'=>'eq', 'Value'=>2] ];

$data['queryParams']['filter'] = [$filter1, $filter2];

        • 可用的过滤器

          • cs: 包含字符串（字符串包含值）
          • sw: 以 ... 开头（字符串以 ... 开头）
          • ew: 以 ... 结尾（字符串以 ... 结尾）
          • eq: 等于（字符串或数字与值完全匹配）
          • lt: 小于（数字小于值）
          • le: 小于等于（数字小于或等于值）
          • ge: 大于等于（数字大于或等于值）
          • gt: 大于（数字大于值）
          • bt: 在 ... 之间（数字在逗号分隔的值之间）
          • in: 在 ... 中（数字在逗号分隔的值列表中）
          • is: 为空（字段包含 "NULL" 值）
          • 您可以通过在前面添加 'n' 字符来否定所有过滤器，因此 'eq' 变为 'neq'。

      • order

        排序参数的索引数组。使用 "order" 参数可以进行排序。默认排序为升序，但可以通过指定 "desc" 来反转。例如

        $data['queryParams']['order'] = ['DispatchTimeStamp,desc'];

        or

        $data['queryParams']['order'] = ['BillTo', 'DispatchTimeStamp,desc'];

      • page

        • 字符串

        • "page" 参数包含请求的页面。默认页面大小为 20，但可以进行调整（例如，调整到 50）。未排序的页面无法进行分页。例如

        $data['queryParams']['page'] = '1';

        or

        $data['queryParams']['page'] = '1,50';

      • join

        • 要使用外键约束连接的表的索引数组。
          $data['endPoint'] = 'clients';
  $data['method'] = 'get';
  $data['queryParams']['filter'][] = ['Resource'=>'ClientID', 'Filter'=>'eq', 'Value'=>0];
  $data['queryParams']['join'] = [ 'config' ];

        此查询将返回具有所有资源的客户以及一个名为 'config' 的额外资源，其中包含该端点上的所有资源。

        如果省略了过滤器，则所有客户都将有额外的资源，但该资源仅对客户 0 进行填充。

        • 当前可用的连接

          • 客户 0 到 config

          • 发票到票

          • 合同运行到合同位置

          • 合同运行到合同运行计划

          • 合同运行到计划覆盖

          • 路线到路线计划

          • 路线到计划覆盖

          • 路线到路线票

公共方法

$query->buildURI();

将 queryParams 属性处理为查询字符串，然后返回自身，以便可以与 call 方法连接。

$query->call();

使用 cURL 库执行查询字符串。返回查询结果或错误时抛出异常。例如

try {
  $query->buildURI()->call();
} catch (Exception $e) {
  return $e->getMessage();
}

LoginHandler

扩展 通用函数

处理登录凭证。

用用户数据填充 $_SESSION。

返回字符串；要么是 '/clients'，要么是 '/drivers'。

出错时抛出异常。

用法

try {
  $handler = new LoginHandler($config, $data);
} catch(Exception $e) {
  return $e->getMessage();
}

在 $data 中可设置的属性

  • clientID

    用户登录名。

    • 重复客户：整数。ClientID。
    • 非重复客户：字符串。以字母 't' 开头的 ClientID。 t1
    • 组织：字符串。 orgLogin
    • 驾驶员：字符串。以单词 'driver' 开头的 DriverID。 driver1
    • 调度员：字符串。以单词 'dispatch' 开头的 DispatchID。 dispatch23

  • upw

    用户密码。

公共方法

try {
  $type = $handler->login();
} catch(Exception $e) {
  echo $e->getMessage();
  return false;
}
echo $type;
return false;

设置以下会话值

$_SESSION['config']

这个关联数组包含来自 配置 端点的资源以及所有客户端 0 资源，除了 Password、AdminPassword 和 Deleted。

$_SESSION['mobile']

如果 true，则此布尔值指示用户从位于 ../mobileLogin 的门户登录，并传递了包含键 "mobile" 的数据集给 LoginHandler 类，将在注销后重定向到该处而不是 /。

$_SESSION['ulevel']

描述登录用户的类型

  • 0: 组织

  • 1: 管理客户端

  • 2: 每日客户端

  • driver

  • dispatch

对应于客户端、组织、驾驶员或调度员的端点上的所有资源，除了 Deleted 和密码。

调度员将 $_SESSION['CanDispatch'] 设置为值 2。

具有调度权限的客户端、调度员和驾驶员将 $_SESSION['config']['ContractDiscount'] 和 $_SESSION['config']['GeneralDiscount'] 设置。这些都是键为客户端 ID（对于非重复客户端，键前有字母 't'）的关联数组，值为每个（或当前）客户端的折扣值。

客户端和组织将设置 $_SESSION['pwWarning']。

整数

  • 0: 密码与登录类型的默认密码不匹配。

  • 1: 每日客户端密码是默认密码

  • 2: 管理客户端密码是默认密码

  • 3: 每日和管理客户端都是默认密码

  • 4: 组织密码是默认密码

这些值用于通知用户应更改密码。

组织将设置 $_SESSION['members']。这是一个关联数组，键为客户端 ID（对于非重复客户端，键前有字母 't'），值为与组织关联的每个客户端在客户端端点存储的数据的关联数组。

Ticket

扩展 通用函数

分别或批量处理和显示票据

用法

try {
  $ticket = new Ticket($config, $data);
} catch(Exception $e) {
  return $e->getMessage();
}

在 $data 中可设置的属性

在 API 文档 中可以找到标准属性列表。

step 属性由 $ticket->updateStep() 使用。

action 属性由 $ticket->cancelTicket() 使用。

特殊属性 multiTicket 可以包含用于批量创建或更新的票据数据集数组。例如：更新两个票据；一个正在递送，另一个返回到同一地址。

$data['multiTicket'] = [
  [
    'ticket_index': 1,
    'step': 'delivered',
    'notes': 'This ticket was delivered'
  ],
  [
    'ticket_index': 2,
    'step': 'returned'
  ]
]

公共方法

echo $ticket->regenTicket();

显示单个票据以供客户审查或调度。

如果拾取、递送或返回步骤的坐标可用，则将在具有类 coordinates 的 span 中显示。

echo $ticket->displaySingleTicket();

显示单个票据以供驾驶员查看。

地址以 a.addressLink 的形式显示，默认情况下将在新窗口中打开 Google Maps 搜索地址。

echo $ticket->displayMultiTicket();

显示具有共同拾取或交付地点和时间的票据组。

地址以 a.addressLink 的形式显示，默认情况下将在新窗口中打开 Google Maps 搜索地址。

echo $ticket->ticketsToDispatch();

检查数据库以查找尚未调度的票据。

echo $ticket->ticketForm();

根据传递给 Ticket 的 $data，有 4 种状态。

1 初始：生成一个空的票据条目表单。

此表单后跟 <div class="mapContainer" id="map"></div>，用于与 JavaScript 地图 API 一起使用。

此 div 只在此步骤中生成。

2 编辑：生成一个填充了提供的 $data 的票据条目表单。

3 确认：生成一个只读表单以进行验证。

在此处解决 TicketPrice。

4 处理：将票据提交到服务器。

在此处设置 TicketNumber。

echo $ticket->runPriceForm();

生成一个简化的票据表单，只接受2个地址、费用和干冰重量。

此表单的数据应传递给$ticket->calculateRunPrice()。

此表单之后跟随<div class="mapContainer" id="map2"></div>，用于与javascript地图API一起使用。

echo $ticket->calculateRunPrice();

注意：在此处调用私有方法self::getTicketBase()，以及创建具有PriceOverride值为0的呼叫票据和合同票据时。此方法使用geocoder-php获取提货和送货地点的坐标。它期望属性$ticket->pAddress2和$ticket->dAddress2的格式为地区/城市，州/省 邮编。这种格式很重要，因为函数会在字符串中（在邮编之前）测试第一个逗号和最后一个空格之间的值与地理编码器返回的值，以确定是否已接收到准确的数据。

返回一个具有以下属性的json编码数组

  • billTo: 客户ID。
  • address1: 提货地址。
  • address2: 送货地址。
  • result1: 地址1的坐标。
  • result2: 地址2的坐标。
  • center: 结果1和结果2之间中点的坐标。
  • pRangeTest: 地址1与RangeCenter之间的距离。
  • dRangeTest: 地址2与RangeCenter之间的距离。
  • rangeDisplay: 地址1和地址2之间的距离。
  • runPrice: 不含干冰的计算价格。
  • ticketPrice: 含干冰的计算价格。
  • diWeight: 用于计算提供的干冰重量。
  • diPrice: 干冰的计算价格。
echo $ticket->fetchTodaysTickets();

检查当前日期给定客户的票据。

对于找到的每个票据，返回$ticket->regenTicket()的结果，如果没有找到则返回false。

$ticket->processRouteTicket();

注意：在计算TicketPrice时，此功能不会显示地图。有关限制，请咨询地理编码器提供商。

处理Route类生成的票据

  • 设置TicketNumber

  • 解决TicketPrice或使用合同运行的端点中存储的资源（如果PriceOverride为true）

  • 提交票据

  • 在合同运行的端点更新LastCompleted日期

成功时返回true，失败时返回false，并可选地记录错误。

$ticket->processReturnTicket();

使用TicketBase中存储的值处理和提交从5到6的费用变更。

echo $ticket->updateTicketProperty();

如果提供，则更新$ticket->updateTicketDatabaseKeys中的值。

$ticket->updateTicketDatabaseKeys = ['BillTo',
                                     'Charge',
                                     'EmailAddress',
                                     'EmailConfirm',
                                     'Telephone',
                                     'RequestedBy',
                                     'pClient',
                                     'pAddress1',
                                     'pAddress2',
                                     'pCountry',
                                     'pContact',
                                     'pTelephone',
                                     'dClient',
                                     'dAddress1',
                                     'dAddress2',
                                     'dCountry',
                                     'dContact',
                                     'dTelephone',
                                     'dryIce',
                                     'diWeight',
                                     'diPrice',
                                     'DispatchedTo',
                                     'Transfers',
                                     'TicketBase',
                                     'RunPrice',
                                     'TicketPrice',
                                     'Notes',
                                     'pSigReq',
                                     'dSigReq',
                                     'd2SigReq',
                                     'pLat',
                                     'pLng',
                                     'dLat',
                                     'dLng',
                                     'd2Lat',
                                     'd2Lng'
                                   ];
echo $ticket->stepTicket();

为单个票据或多票据数组中的给定step设置时间戳并提交，以及注释和其他值。

如果指示，发送确认电子邮件。

成功时返回字符串，失败时返回错误。

错误字符串将包含单词'error'。

有效值

  • 'pickedUp'

    检查$ticket->sigImage

    检查$ticket->latitude和$ticket->longitude

    提交pSigPrint，pSig，pSigType，pLat和pLng

  • 'delivered'

    检查$ticket->sigImage

    检查$ticket->latitude和$ticket->longitude

    提交dSigPrint，dSig，dSigType，dLat和dLng

    如果费用为7且d2SigReq为0，则解决TicketPrice。

  • 'returned'

    检查$ticket->sigImage

    检查$ticket->latitude和$ticket->longitude

    提交d2SigPrint，d2Sig，d2SigType，d2Lat和d2Lng

    如果费用为7且d2SigReq为1，则解决TicketPrice。

  • 'dispatched'

    设置DispatchTimeStamp，DispatchMicroTime，DispatchedTo和DispatchedBy。

echo $ticket->cancelTicket();

处理单个票据或多票据数组中给定的action。

有效值

  • 'delete'

    API使用“软删除”方法。

    票据不会从数据库中删除。相反，费用将被设置为0。

  • 'cancel'

    将票据的费用设置为0。

  • 'deadRun'

    票务费用将被设置为8。

  • '拒绝'

    仅在配送步骤中可用。

    票务费用将被设置为6，并且票价将被重新计算。

  • '转让'

    将更新票务转让状态。

Route

扩展 通用函数

根据“管理运行”页面上的定义为司机创建合同票务。

检查并显示合同票务。

更新最后查看资源。

检查并显示待命票务。

检查并显示已转让票务。

用法

try {
  $route = new Route($config, $data);
} catch(Exception $e) {
  echo $e->getMessage();
  return FALSE;
}

在 $data 中可设置的属性

此类的所有属性都由会话设置。

公共方法

$route->routeTickets();

检查司机最后查看资源。如果它不是当前日期，则将发出调用以检查取消和重新安排，然后创建在“管理运行”页面上定义的票务。然后更新最后查看资源。

注意：上述顺序是优先的。在给定日期取消运行将取代将该运行重新安排到同一日期。重新安排运行将取代其在“管理运行”页面上定义的日期、接货时间、配送时间和返回时间。

将发出调用以获取不完整的常规和往返合同票务。如果此结果为空，则将发出调用以检查当天是否为司机创建了任何合同票务。

具有相同位置和预定步骤时间的多个票务将被分组在一起。

尊重合同运行、合同运行计划、重新安排事件、取消和路线计划的软删除（将“已删除”属性设置为1）。

不尊重与活动合同运行关联的合同位置的软删除。

为每个div.sortable添加一个span.timing元素，供javascript使用，根据票务的ReadyDate和step对票务进行排序。

返回HTML内容。

$route->onCallTickets();

检查在过去7天内已分配给当前司机的未完成待命票务。

返回HTML内容。

$route->transferredTickets();

检查已转交给或由当前司机转让的票务。

返回HTML内容。

Scheduling

静态类，包含用于解释调度代码、文字和索引的工具。

公共方法

Scheduling::codeFromIndex($index);

返回与给定调度_index（1-87）关联的调度代码（[a-g][1-9]或h5 - h28）。

Scheduling::literalFromIndex($index);

返回与给定调度_index（1-87）关联的调度文字（每天、每月最后一个星期四、每22天）。

Scheduling::indexFromCode($code);

返回与给定调度代码（[a-g][1-9]或h5 - h28）关联的调度_index（1-87）。

Scheduling::literalFromCode($code);

返回与调度代码（[a-g][1-9]或h5 - h28）关联的调度文字（每天、每月最后一个星期四、每22天）。

Scheduling::indexFromLiteral($literal);

返回与给定调度文字（每天、每月最后一个星期四、每22天）关联的调度_index（1-87）。

Scheduling::codeFromLiteral($literal);

返回与给定调度文字（每天、每月最后一个星期四、每22天）关联的调度代码（[a-g][1-9]或h5 - h28）。

Scheduling::testIndex($index, $startDate, $testDate);
Scheduling::testCode($code, $startDate, $testDate);
Scheduling::testLiteral($literal, $startDate, $testDate);

比较两个DateTime对象以确定预定间隔是否已过期。

返回boolean。

注意：对于具有天名的“每隔一天”调度，如果起始日期不落在指定的天名上，可能是由于调度已更改，则将测试日期与与起始日期相同的星期天至星期六星期中的预定名称的天进行测试。

例如，如果一个从2017年7月1日开始每周的每个星期六的调度被更改为每周的每个星期二的调度，则当前日期将测试与2017年7月1日同一周的星期二，即2017年6月27日。

Invoice

扩展 通用函数

显示发票以供审查。

默认情况下，取消的票务不会显示。此行为可以在位于extras/includes的配置文件中按客户进行调整。

默认情况下，合同票务按运行编号合并。此行为可以在位于extras/includes的配置文件中按客户进行调整。

用法

try {
  $invoice = new Invoice($config, $data);
} catch(Exception $e) {
  echo $e->getMessage();
  return FALSE;
}

在 $data 中可设置的属性

标准属性列表可在API文档中找到。

invoiceQueryResult 属性是一个索引数组，包含用于从 SearchHandler 类接收数据的发票数据集。

公共方法

$invoice->regenInvoice();

使用 invoiceQueryResult 中提供的数据来显示发票。

如果检测到 dompdf，则将添加一个按钮来显示/下载作为 PDF 的发票。

如果提供了多个数据集，将返回一个表单来选择通过发票号码重新创建哪个发票。

软删除（将 'Deleted' 属性设置为 1）将在发票顶部显示一个悄悄的消息，指出它已被标记为删除。

$invoice->invoiceQueryForm();

为管理员和组织客户创建查询表单。该表单提供的参数由 SearchHandler 类处理。

SearchHandler

扩展 通用函数

接受来自票据和发票查询表单的输入。

返回由相应类处理的那些数据集的 HTML 结果。

用法

try {
  $handler = new SearchHandler($config, $data);
} catch (Exception $e) {
  echo $e->getMessage();
  return false;
}

在 $data 中可设置的属性

  • ticketNumber

    由 ticketLookup() 方法使用。

  • endPoint

    • tickets

    • invoices

  • display

    • tickets: 显示与查询参数匹配的每个票据的 $ticket->regenTicket() 的结果。

    • invoice: 显示匹配发票的 $invoice->regenInvoice() 的结果。

    • chart: 显示由 TicketChart 或 InvoiceChart 类生成的条形图。

  • compare

    当进行跨越多个月份的图表查询时，默认行为是显示查询中的每个月份。将此值设置为 1 将比较查询参数的第一个和最后一个月份。

  • compareMembers

    当进行包括组织多个成员的图表查询时，默认行为是显示每个成员的图表。将此值设置为 1 将比较查询集中的成员。

  • clientID

    与发票关联的客户。

  • billTo

    与票据关联的客户。

  • repeatClient

    • 0: 非重复客户

    • 1: 重复客户

  • startDate

    查询的下界日期。格式 YYYY-mm-dd。

  • endDate

    查询的上界。格式 YYYY-mm-dd。

  • invoiceNumber

    查询特定客户的特定发票。

    预期格式

    • ##EX####-## 正则表达式：/(^[\d]{2}EX[\d]+-[\d]+$)/

    • ##EX####-t## 正则表达式：/(^[\d]{2}EX[\d]+-t[\d]+$)/

  • dateIssued

    查询特定客户发票的月份。格式 YYYY-mm。

  • ticketNumber

    查询特定客户的特定票据。

  • charge

    查询特定客户的特定票据费用。

    值从 0 - 9。

  • type

    查询特定客户的票据类型。

    • 2: 所有

    • 1: 合同

    • 0: 随叫随到

  • allTime

    默认 0。如果设置为 1

    • 如果显示为 "tickets"，则将显示从账户创建到当前日期的所有票据。

    • 如果显示为 "chart"，则将显示从当前日期到上一个 allTimeChartLimit 月份的期间数据。

公共方法

$handler->ticketLookup() ;

使用票据号码获取票据时间信息。

返回一个 JSON 编码的字符串。

如果查询有问题或票据的 Charge 属性为 0（已取消），对象将具有 queryError 属性。

如果没有错误且 Charge 不等于 0，则对象将具有以下属性

  • Charge

    整数

    查询票据的 Charge 属性的值。

  • pTimeStamp

    字符串

    查询票证的pTimeStamp属性值，格式为d M Y \a\t h:i A，或者如果值为NULL则显示“Pending”。

  • dTimeStamp

    字符串

    查询票证的dTimeStamp属性值，格式为d M Y \a\t h:i A，或者如果值为NULL则显示“Pending”。

  • d2TimeStamp

    字符串

    查询票证的d2TimeStamp属性值，格式为d M Y \a\t h:i A，如果值为NULL则显示“Pending”，如果Charge不是6或者Charge是7但d2SigReq不是1则显示“Not Scheduled”。

$handler->handleSearch();

返回指定类（票证、发票、票证图表或发票图表）生成的html内容。

TicketChart

扩展 通用函数

从SearchHandler类接收按月份分组的票证数据集。

显示一个表格，包含给定时间段内每种类型票证的数目。

显示一个简单的条形图，表示给定时间段内每种类型票证的数目。

合同和预约总是显示。

带冰和不带冰总是显示。

所有其他值只有在它们不为零时才显示。

示例

如果检测到dompdf，则会添加一个按钮以显示/下载图表为pdf。

可以在这里找到可以在$config中设置的属性。

用法

try {
  $ticketChart = new TicketChart($config, $data);
} catch(Exception $e) {
  echo $e->getMessage();
  return FALSE;
}

在 $data 中可设置的属性

  • dataSet

    按月份排序的数据的关联数组。

    $monthLabel是票证的ReceivedDate，格式为'M Y'。

    $this->months[$monthLabel][$ticket['BillTo']] = [
                                                 'billTo'=>$ticket['BillTo'],
                                                 'monthTotal'=>1,
                                                 'contract'=>0,
                                                 'credit'=>0,
                                                 'canceled'=>0,
                                                 'onCall'=>0,
                                                 'routine'=>0,
                                                 'fourHour'=>0,
                                                 'threeHour'=>0,
                                                 'twoHour'=>0,
                                                 'oneHour'=>0,
                                                 'roundTrip'=>0,
                                                 'deadRun'=>0,
                                                 'dedicatedRun'=>0,
                                                 'withIce'=>0,
                                                 'withoutIce'=>0,
                                                 'startDate'=>$receivedDate->format('Y-m-d'),
                                                 'endDate'=>$receivedDate->format('Y-m-d')
                                               ];

  • organizationFlag

    布尔值

    指示查询是否针对组织（true）或个人客户（false）。

  • clientID

    数组或整数

    如果organizationFlag是true，则这是一个要查询的成员的索引数组。

    如果organizationFlag是false，则这是当前客户的ID。

  • compare

    布尔值

    指示数据集是两个月比较还是一系列月份。

  • compareMembers

    布尔值

    指示成员是进行比较还是分别显示。

公共方法

$chart = $ticketChart->displayChart();

if ($chart === false) {
  echo $ticketChart->getError();
} else {
  echo $chart;
}

返回html内容或错误时返回false。

InvoiceChart

扩展 通用函数

从SearchHandler类接收按月份分组的票证数据集。

显示一个表格，包含给定时间段内每种类型票证的支出。

显示一个简单的条形图，表示给定时间段内每种类型票证的支出。

只显示非零值。

示例

如果检测到dompdf，则会添加一个按钮以显示/下载图表为pdf。

可以在这里找到可以在$config中设置的属性。

用法

try {
  $invoiceChart = new InvoiceChart($config, $data);
} catch(Exception $e) {
  echo $e->getMessage();
  return FALSE;
}

在 $data 中可设置的属性

  • dataSet

    按月份排序的数据的关联数组。

    $invoiceLabel是发票的DateIssued，格式为'M Y'。

$this->months[$invoiceLabel] = [
                                'invoices'=>[0 => $invoice['InvoiceNumber']],
                                'billTo'=>$invoice['ClientID'],
                                'monthTotal'=>$invoice['InvoiceSubTotal'] - $invoice['BalanceForwarded'],
                                'contract'=>0,
                                'credit'=>0,
                                'canceled'=>0,
                                'onCall'=>0,
                                'routine'=>0,
                                'fourHour'=>0,
                                'threeHour'=>0,
                                'twoHour'=>0,
                                'oneHour'=>0,
                                'roundTrip'=>0,
                                'deadRun'=>0,
                                'dedicatedRun'=>0,
                                'dryIce'=>0,
                                'iceDelivery'=>0,
                               ];
  • organizationFlag

布尔值

指示查询是否针对组织（true）或个人客户（false）。

  • clientID

数组或整数

如果organizationFlag是true，则这是一个要查询的成员的索引数组。

如果organizationFlag是false，则这是当前客户的ID。

  • compare

布尔值

指示数据集是两个月比较还是一系列月份。

  • compareMembers

布尔值

指示成员是进行比较还是分别显示。

公共方法

$chart = $invoiceChart->displayChart();

if ($chart === false) {
  echo $invoiceChart->getError();
} else {
  echo $chart;
}

返回html内容或错误时返回false。

Client

扩展 通用函数

管理客户、司机和调度员的信息。

用法

try {
  $client = new Client($config, $data);
} catch(Exception $e) {
  echo $e->getMessage();
  return FALSE;
}

在 $data 中可设置的属性

标准属性列表可以在API文档中找到。

  • 相同

    指示客户的计费信息与其配送信息相同。

  • currentPw

    要更改的用户的当前密码。

  • newPw1

    新密码。

  • newPw2

    新密码的确认。

公共方法

$client->getAllClientInfo();

返回客户信息的数组。

$client->changePassword();

echo消息并在错误时返回false。

需要提交当前密码。

将提交的当前密码与数据库中存储的散列值进行验证。

测试newPw1是否符合标准

  • 至少8个字符长。
  • 至少一个大写字母。A..Z
  • 至少一个小写字母。a..z
  • 至少一个数字。0..9
  • 至少一个特殊字符。! @ # $ % ^ & * ( ) { } [ ] - _ . : ; , = +

比较newPw1和newPw2以进行确认。

确保管理员和日常用户密码不匹配。

使用PASSWORD_DEFAULT算法和成本12散列新密码。

$client->updateInfo();

echo消息并在错误时返回false。

如果 $client->same 等于 1，则账单信息将被设置为与发货信息相同。

电话号码将通过以下正则表达式进行验证：preg_match('/(\d{3})-(\d{3})-(\d{4})x(\d+)/i', $val) || preg_match('/(\d{3})-(\d{3})-(\d{4})/', $val);。这些模式计划进行更新。

$client->adminPasswordForm();

返回一个设置有管理员用户值的密码更新表单。

$client->dailyPasswordForm();

返回一个设置有每日用户值的密码更新表单。

$client->orgPasswordForm();

返回一个设置有组织用户值的密码更新表单。

$client->driverPasswordForm();

返回一个设置有驾驶员值的密码更新表单。

$client->dispatchPasswordForm();

返回一个设置有调度值的密码更新表单。

$client->updateInfoForm();

仅适用于管理员用户级别。

返回一个联系人信息更新表单。

InvoiceCron

扩展 通用函数

在每月账单周期结束后的一天，自动创建发票，使用 cron 作业运行。

使用新的发票编号更新票据。

可以配置为忽略客户和非重复客户。

根据每张发票中定义的条款检查过期发票。

检查过期发票时，尊重软删除（将 'Deleted' 属性设置为 1）。

用法

  require_once '../includes/api_config.php';
  require_once '../vendor/autoload.php';

  use rjdeliveryomaha\courierinvoice\InvoiceCron;

  try {
    $cron = new InvoiceCron($config);
  } catch(Exception $e) {
    // log $e->getMessage();
    exit;
  }

  try {
    $cron->createInvoices();
  } catch(Exception $e) {
    // log $e->getMessage();
    exit;
  }
  exit;

extras

这是一个使用纯 JavaScript 扩展的此组类的即插即用实现。

功能封装在一个全局变量中： rjdci。

广泛使用 Fetch API，并提供了一个模板。如果由于网络问题导致调用失败，将重试 20 次，每次调用之间等待 n * 250 毫秒，其中 n 是重试次数。如果发送了 FormData 实例，将测试并删除 Content-Type 和 Content-Length 标头，以防止冲突。如果 postData 属性不为空，且 Content-Type 标头设置为 www-form-urlencoded，则将对请求数据进行编码。如果未定义 Content-Type 标头且 postData 属性的长度大于 0，则将 Content-Type 设置为 "application/json"。因此，PHP $_POST 超全局变量不会被填充；必须从流中读取数据。

Ex

  if (empty($_POST)) $_POST = json_decode(file_get_contents('php://input'),true);
  rjdci.fetch_template = async ({ url, method = "POST", headers = {}, postData = {}, retry = 0 }) => {
    if (!url) throw new Error("URL not defined");
    let fetchOptions = {
        method: method.toUpperCase(),
        headers: headers
      };
    if (postData instanceof FormData || Object.keys(postData).length > 0) {
      let body;
      if (postData instanceof FormData) {
        body = postData;
        fetchOptions.headers["Content-Type"] &&
        delete fetchOptions.headers["Content-Type"];
        fetchOptions.headers["Content-Length"] &&
        delete fetchOptions.headers["Content-Length"];
      } else if (fetchOptions.headers["Content-Type"].indexOf("x-www-form-urlencoded") != -1) {
        body = Object.entries(postData).map(([key, value]) =>
          `${encodeURIComponent(key)}=${encodeURIComponent(value)}`).join("&");
      } else {
        body = JSON.stringify(postData);
        if (!headers.hasOwnProperty("Content-Type")) {
          fetchOptions.headers["Content-Type"] = "application/json";
        }
      }
      fetchOptions.method = "POST";
      fetchOptions.body = body;
    }
    try {
      return await fetch(url, fetchOptions);
    } catch(err) {
      retry++;
      if (retry === 20) throw err;
      await rjdci.pause(250 * retry)
      return await rjdci.fetch_template({
        url: url,
        method: method,
        headers: headers,
        postData: postData,
        retry: retry
      });
    }
  }

将 rjdci.pause 函数转换为 setTimeout 并将其转换为 Promise。

  rjdci.pause = duration => { return new Promise(resolve => setTimeout(resolve, duration)) };

用法

  // example taken from rjdci.refreshRoute()
  let postData =  { "formKey": document.querySelector("#formKey").value };
  await rjdci.fetch_templet({ url: "./refreshRoute.php", postData: postData })
  .then(result => {
    if (typeof result === "undefined") throw new Error("Result Undefined");
    if (result.ok) {
      return result.text();
    } else {
      throw new Error(result.status + " " + result.statusText);
    }
  })
  .then(data => {
    if (data.indexOf("error") !== -1) throw new Error(data);
    let parser = new DOMParser(),
      newDom = parser.parseFromString(data, "text/html"),
      docFrag = document.createDocumentFragment();
    Array.from(newDom.querySelectorAll(".sortable")).forEach(element => {
      docFrag.appendChild(element);
    });
    setTimeout(() => {
      document.querySelector("#route").appendChild(docFrag);
      rjdci.assignListeners();
      rjdci.fixDeadRunButton();
      sortRoute();
    }, 2000);
  })
  .then(rjdci.refreshFormKey)
  .catch(error => {
    document.querySelector("#route").innerHTML = '<p class="center"><span class="error">Error</span>: ' + error.message + "</p>";
  });

提供了一个 map 函数的占位符，如果实现了 map API，则应重新定义。

  rjdci.updateMap = ({ coords1, address1, coords2, address2, center, mapDivID }) => { return false; }

Signature Pad v2.3.2 与 extras/public_html/app_js/sigPad.js 预配置，以收集签名，并与函数 $ticket->displaySingleTicket() 和 $ticket->displayMultiTicket() 一起使用。

提供了 rjdci.toast(msg, options) 方法。它创建并删除一个类似 toast 的 div 来向用户显示消息。

用法

  let options = {},
      msg = "Test Message"; // or ['Test Message'] or [ 'Multi-line', 'Test Message' ];
  options.title = "sample div title"; // title attribute of toast div. default ""
  options.time = 3000; // milliseconds to show toast div. div will be removed 1 second after it is hidden. default 4000
  options.eleClass = "ticketOncallReceived"; // custom class for the toast div. The function will display only the newest of a custom class, removing previous messages. All default class divs will be displayed for the configured time. default "toast__msg"
  options.datatime = 1512574797926; // unix time stamp to parse for display with message. default new Date().getTime();
  rjdci.toast(msg, options);

可以通过调用 rjdci.getSpinner() 方法来返回加载图标的一个副本。

功能

使用数据库中的票据信息填充 datalist 元素，以协助表单填写。

单页设计，可以通过滑动或菜单导航。根据用户类型提供独特功能。一旦加载了每一页，就会触发一个窗口事件 rjdci_loaded。

使用 Swipe 进行导航。可以通过 rjdci.Swipe 实例访问 Public methods。

在页面之间转换结束时，调用 scroll(0,0) 并触发一个窗口事件 rjdci_pageChange。

在 extras/includes 中找到的配置文件中处理菜单项的顺序以及添加自定义菜单项（带或不带匹配页面）和 JavaScript 文件。

驾驶员

如果用户代理同时支持权限和地理位置API，则在取票、派送、退票、拒绝或标记为死跑时将尝试获取坐标。上述描述的函数rjdci.toast用于创建具有类deliveryLocation的通知，以告知用户更新派送位置的进度。

  • Route

    • 使用Route类创建或检索指定司机的合同票。

    • 将匹配位置和时间的票进行分组。

    • 显示单张和分组票，并具有以下功能：

      • 收集签名

      • 更新步骤

      • 更新备注

      • 取消

      • 标记为死跑

      • 转让

    • 可以独立刷新。

      • 自定义事件rjdci_refreshed，其中e.detail.type() = "route"
        在刷新完成后触发。

  • 呼叫中

    • 使用Route类检索指定司机的呼叫中票。

    • 显示单张票，并具有以下功能：

      • 收集签名

      • 更新步骤

      • 更新备注

      • 取消

      • 标记为死跑

      • 转让

    • 可以独立刷新。

      • 自定义事件rjdci_refreshed，其中e.detail.type() = "oncall"
        在刷新完成后触发。

  • 转让

    • 使用Route类检索由指定司机转让或转让给指定司机的票。

    • 将匹配位置和时间的合同票进行分组。

    • 显示单张和分组票，并具有以下功能：

      • 接受转让

      • 拒绝转让

      • 取消转让

    • 可以独立刷新。

      • 自定义事件rjdci_refreshed，其中e.detail.type() = "transfers"
        在刷新完成后触发。

  • 司机票务录入和派发页面，适用于具有派发权限的司机。以下将进行描述。

  • 司机活动票务页面，适用于具有派发权限的司机。以下将进行描述。

  • 更改密码

    • 提供一个简单的表单来更新密码

调度员

  • 调度

    • 使用Ticket类检查尚未派发的票。

    • 显示单张票，并具有派发功能。

    • 可以独立刷新。

      • 自定义事件rjdci_refreshed，其中e.detail.type() = "dispatch"
        在刷新完成后触发。

  • 价格计算器

    • 紧凑型票务表单

    • 仅接受取货地址、派送地址、费用和干冰信息

    • 使用Ticket类计算票务价格

    • <div class="mapContainer" id="map2"></div>可用于显示地图

  • 活动票务

    • 查询指定司机的合同或呼叫中票

    • 显示单张票，并具有编辑功能

  • 票务录入

    • 用于提交票务到API的表单

    • <div class="mapContainer" id="map"></div>可用于显示地图

    • 可以独立刷新。

      • 自定义事件rjdci_refreshed，其中e.detail.type() = "ticketEntry"
        在刷新完成后触发。

  • 更改密码

    • 提供一个简单的表单来更新密码

客户

  • 管理员用户

    • 派送请求表单

      • 用于提交票务到API的表单

    • 票务查询

      • 可以通过票号或日期搜索票务

      • 显示单个票务或表示票务量的条形图

      • 条形图可以覆盖一定范围的月份（最大值可配置）或比较两个月

      • 可以分别配置管理员和日常用户查询的票务费用

    • 发票查询

      • 可以通过发票号或日期搜索发票

      • 显示单个发票或表示支出的条形图

      • 条形图可以覆盖一定范围的月份（最大值可配置）或比较两个月

    • 密码管理

      • 更新管理员或日常用户的密码

      • 警告从默认密码更改

    • 联系信息管理

    • 价格计算器

  • 日常用户

    • 派送请求表单

    • 票务查询

    • 价格计算器

组织

  • 价格计算器

  • 票务查询

    • 可以通过票号或日期搜索票务

    • 可以按个人成员或成员组搜索

    • 显示单个票务或表示票务量的条形图

    • 条形图可以覆盖一定范围的月份（最大值可配置）或比较两个月

  • 发票查询

    • 可以通过发票号或日期搜索发票

    • 可以按个人成员或成员组搜索

    • 显示单个发票或表示支出的条形图

    • 条形图可以覆盖一定范围的月份（最大值可配置）或比较两个月

  • 密码管理