包简介

An extension to Jens Segers Agent tool for querying user agent data.

README 文档

README

Installation

composer require marknotton/agent

Official Documentation

This really is just an extension to Jens Segers Agent utility. Refer to their documentation for all available methods.

Whilst I have tried to keep this plugin as lean as possible, I have extended Jens Segers Agent utility by including a couple of my own methods...

Check

Check to determine the users browser and version type is a match.

Example 1:

true if the users current browser matches either browser name

{{ craft.agent.check('edge', 'firefox') }}

Example 2:

You can use most comparison operators to match against the browsers version.

true if browser version is equal to 100:

{{ craft.agent.check('chrome == 100'}}

true if browser version is not equal to 100:

{{ craft.agent.check('chrome != 100'}}

true if browser version is less than 100:

{{ craft.agent.check('chrome < 100'}}

true if browser version is greater than 100:

{{ craft.agent.check('chrome > 100'}}

true if browser version is less than or equal to 100:

{{ craft.agent.check('chrome <= 100'}}

true if browser version is greater than or equal to 100:

{{ craft.agent.check('chrome >= 100'}}

Example 3:

You can add multiple criteria for your check. true if any criteria is a match:

{{ craft.agent.check('ie 9', 'chrome > 49', 'firefox') }}

Example 5:

You may also negate a check by prefixing a not string. true if the users current browser is not IE version 9 or above.

{{ craft.agent.check('not ie => 9') }}

User agent whitelist:

If the User Agent contains any whitelist exceptions, even with partial matches, then the Check method will always return true. This can be useful for allowing certain bots to pass the Check method.

You can mange the whitelist by creating an agent.php config file in your projects configs directory:

return [
'userAgentWhitelist' => [
	'APIs-Google',
	'Mediapartners-Google',
	'AdsBot-Google',
	'Googlebot-Image',
	'Googlebot',
	'FeedFetcher-Google'
	]
];

or via the CMS plugin settings:

Version

Jens Segers original version method required a property name (browser, platform, os, etc...); and the return value would resolve to a full schema version:

{{ craft.agent.version(craft.agent.browser) }} // 104.3.0.1

I have found in most cases getting the major browser version would suffice. So instead of the previous example you can return a 'floored' version number where the browser is the assumed default argument.

{{ craft.agent.version() }} // 104

You can still get full version or a floated version number like so:

{{ craft.agent.version('text') }} // 104.3.0.1 
{{ craft.agent.version('float') }} // 104.3

Redirect

Redirect users to a new template/url if the user agent doesn't match any of the check method criteria:

{% set criteria = [
  'chrome > 55',
  'firefox > 44',
  'safari >= 7',
  'edge >= 15',
  'opera > 50'
] %}

{{ craft.agent.redirect(criteria, 'no-support.twig', 302) }}

Data

To set the user agents device name, version and device type directly to an element. Use Crafts attr method to render common data attributes.

<html {{ attr({ data : craft.agent.commonData() })}}>

The end result will look like something like this:

<html data-browser-name="chrome" data-browser-version="103" data-device="desktop">

But why would you want this? This opens up some options for browser specific styling within your CSS; and this server side approach will omit flashes of unstyled content (FOUC) or layout shifts because styling rules aren't dependant on Javascript during page load. This means you can confidently use something like this in your CSS:

html[data-browser-name="safari"] article img { ... }

agent.js

There is a small IIFE agent.min.js (< 0.7k) file that can be injected directly into the <head>. You'll need to enable this via the plugin settings.

This will define global properties to the window object for the browser name, version, and different device types.


`window.browser.name`	string
`window.browser.version`	int
`window.device`	string
`window.isPhone`	bool
`window.isTable`	bool
`window.isDesktop`	bool

Alternatively you can register the the agent.min.js asset manually:

Twig:

{{ craft.agent.registerAgentJsFile(<useCompressedFile:bool>, <position:string>) }}

Php:

Agent::registerAgentJsFile(<useCompressedFile:bool>, <position:string>);

Change Log & Breaking Changes

There have been many changes since the previous version of Agent 1.2.0. Some for performance, some for sanity. Arguably some practices used in the previous version were over engineered for no obvious gains. These changes could be breaking, that require small syntax tweaks to resolve on older projects. Please review the "4.0.0 - 2022-09-11" change log for suggestions and fixes.

marknotton/agent 适用场景与选型建议

marknotton/agent 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 27.07k 次下载、GitHub Stars 达 7，最近一次更新时间为 2018 年 03 月 19 日，在 PHP 生态内属于活跃度较高的组件。

我们在过去多个企业项目中使用过 marknotton/agent 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 marknotton/agent 我们能提供哪些服务？

定制开发 / 二次开发

基于 marknotton/agent 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

marknotton/agent

包简介