README

Simple Counter 是一个简单的PHP计数器，用于统计您的网站访问者。它可以将计数显示为纯文本或图像；并且可以选择仅计算唯一点击或所有点击。（基于IP）

重要提示

从v6.0.0版本开始，Simple Counter不再使用GNU LGPLv3许可证。
v6.0.0是对库的完全重写，不再保留任何GNU LGPLv3许可证的代码。
v5.0.1及以前的版本仍使用GNU LGPLv3许可证。

因此，如果您是从旧版本升级的，请务必阅读下面的《升级》部分。

鸣谢

默认图片集（在counter/images/中找到的0-9 'png'图片）的图标是根据CC BY 4.0 DEED许可证许可的，并由StreamlineHQ设计。

升级

Pre-v6 -> v6不是简单的升级。在这个重写中，有几个地方发生了变化，并且有一些破坏性的变化。

在尝试升级之前，请先阅读UPGRADING.md。

安装

要安装Simple Counter，首先通过composer安装

composer require esi/simple_counter:^6.0

默认情况下已定义了几个选项，但如果不更改其中的一些，您可能会遇到问题。更多信息请参阅下面的用法。

将counter目录从vendor/esi/simple_counter复制到您的网站根目录
- counter目录包含logs和images目录。
- 如果您愿意，可以更改这两个目录中的任何一个名称，或者完全跳过使用counter目录，只需将logs和images移动到您的网站根目录。
  - 然而
    - IP文件和计数文件必须保持为ips.json和counter.json
    - 图像必须命名为0-9。
请确保您日志目录中的ips.json和counter.json文件可写。

用法

更详细的文档正在编写中。

安装后，用法相当简单。目前有一个选项用于您希望使用的计数器类型，那就是FlatfileStorage。预计在未来的版本中将包含DatabaseStorage。

只需将以下代码添加到您希望显示计数器的页面中

<?php

// Load the composer autoload file, if not already loaded
require_once 'vendor/autoload.php';

use Esi\SimpleCounter\Counter;
use Esi\SimpleCounter\Storage\FlatfileStorage;
use Esi\SimpleCounter\Configuration\FlatfileConfiguration;

/**
 * $options is an array of:
 *
 * array{
 *     logDir: string,
 *     countFile: string,
 *     ipFile: string,
 *     imageDir: string,
 *     imageExt: string,
 *     uniqueOnly: bool,
 *     asImage: bool,
 *     honorDnt: bool,
 *     visitorTextString?: string
 * }
 *
 * Default values are:
 *
 * [
 *      'logDir'            => dirname(__DIR__, 2) . '/counter/logs/',
 *      'countFile'         => 'counter.json',
 *      'ipFile'            => 'ips.json',
 *      'imageDir'          => dirname(__DIR__, 2) . '/counter/images/',
 *      'imageExt'          => '.png',
 *      'uniqueOnly'        => true,
 *      'asImage'           => false,
 *      'honorDnt'          => false,
 *      'visitorTextString' => 'You are visitor #%s',
 * ] 
 */
// Valid options are:
$options = [
    'logDir'            => '/path/to/some/dir/logs',
    'countFile'         => 'counter.json',
    'ipFile'            => 'ips.json',
    'imageDir'          => '/path/to/some/dir/images',
    'imageExt'          => '.png', // '.png', '.jpg' etc. default images are PNG images
    'asImage'           => true,   // true = images, false = plain text
    'uniqueOnly'        => true,   // true = counts only unique ip's, false = counts all,
    'honorDnt'          => false,
    'visitorTextString' => 'You are visitor #%s',
];

/**
 * Important note regarding the 'visitorTextString'. This is the text that is shown if 'asImage' is false.
 *
 * For example, by default, it would show: You are visitor #123.
 * If you wanted to change it to something like: Counter: #123,
 * you would set the 'visitorTextString' option to:
 * 
 * 'Counter: #%s'
 */

/**
 * When creating the counter instance, a Storage implementation with a valid Configuration is required.
 * Currently, Simple Counter ships with one Storage implementation, and it's corresponding Configuration:
 *
 * \Esi\SimpleCounter\Storage\FlatfileStorage
 * \Esi\SimpleCounter\Configuration\FlatfileConfiguration
 *
 * \Esi\SimpleCounter\Counter can be used as a wrapper, but it is not necessary. For example:
 *
 * $counter = new Counter(
 *     new FlatfileStorage(
 *         FlatfileConfiguration::initOptions($options)
 *     )
 * );
 */
// Pass custom options
$counter = new FlatfileStorage(
    FlatfileConfiguration::initOptions($options)
);

// ... or if you wish to use defaults
$counter = new FlatfileStorage(
    FlatfileConfiguration::initOptions()
);

// ... or maybe you only want to switch to using images, for example
$counter = new FlatfileStorage(
    FlatfileConfiguration::initOptions(['asImage' => true])
);

// Finally, call display(). You can either output it directly or save it to a variable if needed
echo $counter->display();

// ... or ...

$hitCount = $counter->display();

// ... do some stuff
echo $hitCount;

?>

错误处理

Simple Counter在其过程中可能会遇到各种问题，它使用异常来处理这些问题。

目前，大多数异常都归入\Symfony\Component\OptionsResolver\Exception\InvalidOptionsException。

如果发生以下情况，可能会抛出这些异常：

传递了一个未定义的选项。
给定选项的值类型与允许的类型不匹配。
在读写文件时遇到错误，因为这很可能是由于文件名/位置问题。
对于无效的目录或文件，就logDir、imageDir、countFile、ipFile而言

关于

需求

Simple Counter 支持PHP 8.2.0或更高版本。

提交错误报告和功能请求

错误报告和功能请求在 GitHub 上跟踪

问题是最快报告错误的方式。如果您发现了一个错误或文档错误，请首先检查以下内容

没有关于此错误的已开放问题
该问题尚未被解决（例如，在已关闭的问题中）

许可证

Simple Counter v6.0.0及更高版本

根据MIT许可证授权。有关详细信息，请参阅 LICENSE.md 文件。

Simple Counter v5.0.1及更早版本

根据GNU LGPL v3许可证授权。有关详细信息，请参阅 <= 5.x LICENSE.md 文件。

esi / simple_counter

维护者

详细信息