Copyright and License

It's a universal counter script. ... v5.2.0!

Index

Installation
- Dependencies
Screenshots
Directory structure
Details
- Security
- Storage
- Server and/or Client
- Refresh
- Override
  - Static mode
- Overwrites
- Cleaning
- Privacy
- Errors
- String filter
- Security test
Drawing
- Parameters
- Dependencies
Configuration
Modes
Exports
Modules
FAQ
TODO
The original version
Copyright and License

Updated

[2024-11-04]; to v5.2.0!

Installation

The easiest way is to just use this count.php with it's default configuration: copy it to some path in your htdocs/, and That's all! :-) The configured counter directory count/ will automatically be created.

Warning If your HTTPD uses another user than you've for regular use, you maybe would like to adapt KEKSE_MODE_{DIR,FILE}! It's an open door for other users on the system, but if you really need console access under this circumstances, you'd like to do this..

Note I'd suggest you to also copy the count.sh (wrapper) shell/bash script to easily execute the script in it's CLI mode! Download it into the same directory as the count.php and set (just once) chmod +x count.sh! You can symlink to it from everywhere, it'll always use the count.php from within the same directory where the script's located at.

The possible, possibly complex rest is described in the Configuration section.

As an important example, hence here's another file system change necessary: if you want to enable the drawing routines. Then the HTTPD needs access to a sub directory fonts/, with at least one installed font in it (which you need to set as the default font in the font setting).

Warning FreeType seems to only support .ttf fonts. My script is adapted to this, so other font formats are not supported.

Note You can just use the fonts/ shipped with(in) this repository.

Warning It may be unsafe to store the count/ directory inside your web root (even though you use a .htaccess), so install it somewhere out there and adapt your path configuration.

So, that's all. :D~

Note If you want to edit the default configuration, take at look at the Configuration section. And to make sure your settings are valid, you can call this script like this: php count.php --config / -c.

Dependencies

NO dependencies.

Except if you're enabling the drawing configuration. In this case it's the GD Library. More infos below, in the Drawing section and it's drawing dependencies sub section.

Screenshots

See the GET-Parameters of these screenshots.

The first one is with text mode (to scramble a mail address, e.g.). The second one is with radix/base 36 (like a binary digit, but with base 36, as example). The third one is the CLI mode, to manage the script within a terminal.

Directory structure

This is the structure of the file system of this Git repository, jfyi:

Directory	Description
`count/`	The default directory for all values, caches, etc. (plus .htaccess to deny direct reading);
`docs/`	`.md` documentation, and it's example screenshots/images (so: github internal);
`fonts/`	Pre-installed fonts (used when drawing the counter values etc.) (plus .htaccess to deny direct reading);
`modules/`	This is only a future possibility.. nothing which is used right now (so can be left out);
`php/`	Mainly the source itself (plus a bit rest, feel free to ignore it [should be symlinks, maybe]);
`sh/`	The wrapper shell script, to call the `count.php` via command line (within correct directory boundings);

Details

Note You can easily manage all the values etc. via command line! Look at the CLI mode section for details.

text/plain

By default the script generates a text/plain (plus charset) output, so you can easily embed the counting value via XMLHttpRequest() or the Fetch API. This Content-Type (a HTTP header) is configurable via the content setting (see the Configuration section).

This is preferred if you'd like to fit the counter's style exactly to your website. You can define every (CSS) details, etc.

Image

The other way is to embed the counter as (server-side drawn) <img> (png and jpg types supported). That's also good, and a lot easier to embed (for the most)!

Especially useful on a site like this one (github.com), where you can't just script anything..

Warning For this to work the drawing configuration needs to be enabled (is the default). But then fonts must be installed!

On top of this README.md I included my (private) counter via HTML <img> tag. .. worx!

Security

I was very concerned about the security.. there are many features for this, so I'm not going to explain you all the details in this Details section. If you'd like to know more, just continue reading this whole documentation, or maybe even read the fucking source! ;)~

And I'm also not going to explain all the configuration details in this overview. Just read further, again..

Storage

Instead of using big databases or an own format in one file or so (what I preferred in ~~1998~~ ;-), I'm chosing the file system as very efficient carrier! Really, it's much performance in it!

Note Take a look at the File Scheme sub section, to get to know which files are being used (which are real counter items of your base counter directory)!

It's used to store the counted values itself, one file per host. And if server setting is enabled, it also creates a directory for each host, where every IP address (or their hashes, if Privacy is a concern) will take one file each. If you configured it, they'll also be cleaned, as often as you defined it (even though you can define to never delete any such file, to protocol the IP's, e.g.).

These IP files (with timestamps in it) will also use own cache files, one per host, where the amount of them is managed. So if their amount is necessary to know, no repetition of scandir() (used opendir() and readdir() most times) is always slowing down things..

Warning All files got limits .. for sure. And there's also a limit for automatical creation of files.

Server and/or Client

If a cookie (if actived client) already confirmed that the client connected within the threshold (2 hours by default), no server test will be done after this. And if a cookie doesn't work, there's still this IP test left (if server enabled).

Warning If threshold == 0 or threshold === null, both server and client will be overridden (to false); as this seems you don't need a threshold time.

Refresh

If you are able to reload the counter dynamically on your web sites, please do it.

This would be great, because with every poll the timestamps get updated, so the threshold setting (which gives you the logical, maximum time to refresh, btw.) is not the only prevention against multiple countings; periodically polled it makes you some 'session' styles by adapting the timestamp, that will never get too old this way.

So, if you're periodically polling this script (I'm doing it via XMLHttpRequest()), the client is not being counted again after the threshold time over this 'session', until he disconnects. Then coming back again after the two hours (by default) he will get counted again. Pretty easy?

Override

If(override === true), one can call the script's URL with ?override=(string), so neither regular $_SERVER['HTTP_HOST'] nor $_SERVER['SERVER_NAME'] are being used, but an arbitrary (but filtered) string (or just another host you define there).

Warning On any override, it's expected this ain't a real host or smth.. so the makeCookie() is disabled then!

I don't really like it, but if you need this feature, just use it. Works great.

Warning The auto setting is also overridden in this case, so it's not possible to always use any arbitrary parameter (also important for security). Thus, you first have to create a value file to the corresponding string!

And now the override setting can also be a (non-empty) String, to define just one fixed host(name) (or an more or less arbitrary (but filtered, see secureHost()) identifier String) to use.

Every override set's the state (see {get,set}State()) overridden = true.

Static mode

Beneath a Boolean type the override can also be one string. In this case, only for this one 'host' will be counted! It's useful for only one website, and even if you GET it with https://host or https://www.host, maybe https://subdomain.host or even https://127.1 or so, only ONE value will be counted!

Overwrites

Beneath the default configuration, any host (within the file system, as desribed above at Storage) can have it's own configuration (difference) file, to apply these only to these hosts itself. This is really optional, but could maybe be very useful sometimes.

It came up since in earlier versions I defined the whole configuration via define(), which ended up in (too much) global (namespace) declaration.. BAD. So now everything works even better than before this way (and nearly no define() is being used now - except some in my own namespace).

Note For more infos, see the Per-host config overwrite sub section!

Cleaning

If configured, out-dated ip/timestamp files will be deleted (this and more is also possible in the CLI (cmd-line) mode), if their timestamps are 'out-dated' (so if they have been written more than threshold (by default 2 hours) seconds before).

If you define an (integer), the cache will be cleared only if there are more files existing than the (integer).

Warning If you set it to (null), every cleaning is forbidden, if you want to collect all the IPs? (false) would also never call the clean routine, except if the limit is exceeded.

Privacy

And if privacy is one of your concerns, the IPs (in their own files with their timestamps) can also be hashed, so noone can see them (including yourself, or the webmaster(s), .. even with access to the file system). .. just enable the privacy setting.

Errors

Log to file

Most errors will be appended to the count.log file (configurable via log), so webmasters etc. can directly see what's maybe going wrong. But due to security, not everything is being logged. Especially where one could define own $_GET[] or $_SERVER[] or so, which could end up in flooding the log file!

Note Logging with timestamps: seconds since the UNIX epoch (the January 1st, 1970).

Note Parsing this log file is easy: it begins with [$timestamp] and optional $_source($_path); after this a regular colon with space : starts the $_reason string itself. So you can use cut -d':' -f{1|2} $file to extract either the extended infos (-f1) or the reason/message itself (-f2).

Warning As cut only handles one-char -d delimiters, you can't include the following space here. But you can substr() the message. In the bash, this is done via ${line:2}. But best 'd be to split() or smth. similar by string : (a colon and a space)!

String filter

All $_SERVER[] and $_GET[] are filtered to reach security (please don't ever trust any [user] input!).

I just abstracted both functions secure{,Host,Path}() to only one function, which is partially also used by the getParam().. both functions stayed: they internally use secure(), but the secureHost() additionally does a strtolower() (via parameter which is passed straight to the base secure() (afair).

So here you gotta know which characters you can pass. The maximum length is 224 characters (by default, look at the KEKSE_LIMIT_STRING constant), btw.

a-z
A-Z
0-9
=
#
,
:
(
)
/ (limited)
. (limited)
+ (limited)
- (limited)
_

That's also important for the optional ?override= GET parameter (see above), e.g., as hosts (etc.) also won't ever be accepted 'as is'.

So I'm also securing the used $_SERVER[] variables, as e.g. via Hostname: ... in the HTTP header the host could be poisoned as well!

FQDN's

Note The string filter (above) also removes any trailing . from the hostnames; so if you call from a web browser with a hostname plus trailing dot ., which is a FQDN, it'll be removed, so the counting is not disturbed (otherwise it would end up in another file for w/ and w/o .)!

Security test

Beneath some more or less routines I even added some basic, abstract file operation functions, which I'm using only instead of the regular ones (listed below), and in the checkPath().

Note It's more or less nearly too much, but it's the last possibility for security, if the string filter failed or smth..

This securityTest() function checks:

If path is really a string
If path starts with / (all used paths are resolved)
If any path component is ..
Most times also if path is below one of the counter base paths (as follows)

Used base paths of the counter are: [ path, log, fonts, modules ].

Drawing

The normal way is to return the plain value (by default w/ Content-Type: text/plain;charset=UTF-8), but I've also implemented some drawing routines, to embed the counter value as <img>.

If allowed by drawing setting, just use either ?draw for all possible options, or just ?zero to draw a (nearly) empty output image (hidden counter, e.g. .. whereas there's also the hide setting!).

Parameters

To use it, enable the drawing option and call script with (at least!) ?draw [or ?zero] (GET) parameter. More isn't necessary, but there also also some GET parameters to adapt the drawing, as follows..

Note Such GET parameters need a prefix before the variable name. It's either ? for the first parameter, or & for all following ones. They are defined in the request URL!

Variable	Default Settings [= (value)]	Type	Description / Comment(s)
`draw`	(`drawing` needs to be enabled!) = `false`	No value	By default no <img>
`zero`	(`drawing` again) (overrides the options below)	No value	Alternative to `?draw`
`size`	`64px`	String/Double	>= 3 and <= 512, `32px`, `24pt`
`scale`	`false`	Boolean	Instead of fixed `?size`, fit the image to the drawn text/value
`unit`	`px`	String	If `size` is w/o `unit` suffix
`font`	`Candara`	String	Also see `fonts`
`fg`	`0, 0, 0, 1`	String	See Colors
`bg`	`255, 255, 255, 0`	String	See Colors
`angle`	`0.0`	String/Double	Anticlockwise [ '', 'deg', 'rad' ]
`h`	`0.0`	String/Double	>= -512 and <= 512, `32px`, `24pt`
`v`	`0.0`	String/Double	>= -512 and <= 512, `32px`, `24pt`
`x`	`0.0`	String/Double	>= -512 and <= 512, `32px`, `24pt`
`y`	`0.0`	String/Double	>= -512 and <= 512, `32px`, `24pt`
`type`	`'png'`	String	See `--types / -t`
`text`	(`drawing` thing, but for regular text strings	String	See configuration `text`; combined w/ any of here

Note Double and Float are two different types in many languages (4 vs. 8 bytes long, or 32 vs. 64 bits), but in PHP they seem to be exactly the same! I choosed the double notation here, because that's what gettype() returns. ;-)

Explaination

size is either an Integer or Double/Float. In this case the optional unit is considered (also in the configuration). Or it can also be a String with unit suffix [ px, pt ]. unit can have one of these both strings, but will not be used if size is already with (valid) suffix!

scale can get y[es]/n[o]/1/0/-/+ as $_GET[] value. If not defined, we're using the getConfig() function to read the (current, also overwritten) configuration. If set to true, the image won't be scaled up to the real ?size parameter value, but will be reduced in it's size as much as possible (to perfectly fit the text/value). ... It is NOT the default setting, because I like to get an image with the size I really define.. and it fits better into the line alignment.

So, unit sets the default unit to use for h, v, x, y and size, if there are only Integer/Double values, not a String with unit suffix.

The selected font needs to be installed in the fonts directory, as .ttf. The parameter is normally without '.ttf' extension, but this doesn't matter at all.

fg and bg are colors, see the Colors sub section of the Configuration section.

angle will rotate the whole image anticlockwise (or just use negative values! ;-) .. supported are either integer or double/float values (assumed as being in 'degrees'), and Strings with a unit [ deg, rad ] as suffix.

x and y are just moving the text along these both axis. v is the space above and below the text, h is to the left and the right. They all can also be negative values, and can be with or without unit suffix. If no suffix defined, they'll be scaled by using the ?unit (or the value in the configuration(s), if not defined as parameter).

Last but not least, the ?type can atm be set to png and jpg, whereas png is absolutely preferred (example given: jpg does not have the best alpha-channel (transparency) support)!

And now, new: ?text drawing, mostly intended for 'secure' drawing E-Mail addresses, without that crawlers or bots can automatically extract these links...

Note All parameters are optional, but only the ?draw isn't, and needs to be set if you want a graphical output. ?zero is also enabling drawing mode, but you won't see anything at all ... and this, and only ?zero and ?text can be set without ?draw, to draw nevertheless..

Dependencies

Libraries

Warning The GD Library has to be installed for this feature.

Note The GD library also needs 'FreeType' support with it, as we're drawing with True Type Fonts (this is not checked within --config / -c, btw.).

Runned by a web server with enabled drawing option and also aktived via ?draw will only call this drawing mode if module is installed. If not, the regular (text/plain) output will nevertheless be used; to avoid error output (even though it's bad that you're using an <img> tag..... but error output wouldn't be visible in this case at all).

Fonts

The second dependency is a configured fonts directory with (.ttf) font(s) installed in it (and if you don't specify this via ?font it really needs to be pre-set via font setting); ...

Note I'd recommend to replace remove space in the font filename (etc.) to 'beautify' your $?font=* parameters.

Configuration

The configuration is an associative array of various settings.

You can test if they are valid by using the --config / -c command line argument (with optional argument(s), see the Per-host config overwrite section below).

No more constants.

Here are the current default settings, including the possible types

Note Every variable with a big, bold ⚠️ will never be overwritten by any per-host config overwrite. But this will always be checked (injection not possible).

This $DEFAULTS are stored in the script file itself, on the top. You can leave them as my defaults, and better 'd be to use a count.json in the same directory where the count.php (or a symlink) resides; they'll overwrite the $DEFAULTS.

Warning So PLEASE use a count.json in the same directory where your file/symlink resides! If you update the script itself, then your configuration will stay as it was, customized by you!

Note The .json mentioned above should be named the same as the count.php itself (so the basename without extension). So if you call this script e.g. counter.php, your config file should be counter.json.

..	Name	Default value	Possible types/values	Description / Comment(s)
⚠️	`path`	`'count/'`	String (non-empty)	See Relative paths below
	`text`	`32`	Boolean/Integer	Whether to allow text drawing; Integer is char max
	`log`	`'count.log'`	String (non-empty)	File to log errors to (also see link above)
	`threshold`	`7200`	Integer/NULL	How long does it take till counting again?
	`auto`	`32`	Boolean/Integer/NULL	Create count value files automatically?
	`hide`	`false`	Boolean/String/Integer	Show the counted value or hide it?
	`client`	`true`	Boolean/NULL	Enables Cookies against re-counting
	`server`	`true`	Boolean	Enables cache/ip/timestamp files, like above
	`drawing`	`false`	Boolean	Essential if using `?draw` or `?zero`!
⚠️	`override`	`false`	Boolean/String (non-empty)	Instead of using `$_SERVER[]` `$_GET[]` or String
	`content`	`'text/plain;charset=UTF-8'`	String (non-empty)	Non-graphical mode produces only value output
	`radix`	`10`	Integer	See Radix below .. change the output(s)
	`clean`	`true`	NULL/Boolean/Integer	Clean outdated cache files and the FS things?
	`limit`	`32768`	Integer	Maximum number of files, in base dir and sub dir!
	`fonts`	`'fonts/'`	String (non-empty)	Directory with installed '.ttf' fonts @ path
	`font`	`'Candara'`	String (non-empty) [see `--fonts / -f`]	Default font to use
	`size`	`64`	String/Double (>=3 and <=512)	Either Double, w/ `unit`, or String `pt` or `px`
	`unit`	`px`	String [ `pt`, `px` ]	Will be used if `size`/`x`/`y`/`h`/`v` is numeric.
	`fg`	`'rgb(0, 0, 0)'`	String (non-empty)	See Colors below
	`bg`	`'rgba(255, 255, 255, 0)'`	String (non-empty)	See Colors below
	`angle`	`0`	Double/String	Anticlockwise rotation; (int) vs. `deg` or `rad`
	`x`	`0`	Double/String (<=512 and >=-512)	Movement of drawed text left/right
	`y`	`0`	Double/String (<=512 and >=-512)	Same as above, but for up/down
	`h`	`0`	Double/String (<=512 and >=-512)	Horizontal space from text to end of image
	`v`	`0`	Double/String (<=512 and >=-512)	Vertical space, like above
	`type`	`'png'`	String (non-empty) [see `--types / -t`]	Only `png` and `jpg` supported 'atm' (are best!)
	`privacy`	`false`	Boolean	Hashes the IPs (stored if `server` is enabled)
	`hash`	`'sha3-256'`	String (non-empty) [see `--hashes / -h`]	This is the hash algorithm. Used for Cookies, too
	`error`	`null`	NULL/String	If not (null), it will be shown on any error
	`none`	`'/'`	String	And this is shown when `!auto` w/o value file..

It'd be better to create a .htaccess file with at least Deny from all in your path directory. But consider that not every HTTPD (web server) supports such a file (e.g. lighttpd..)!

Note Same as above: in PHP Double and Float are the same. But double is what gettype() returns.

Per-host config overwrite

The per-host configuration allows a sub-set of settings (look at the CONFIG_STATIC const array) to 'overwrite' the default configuration (see $DEFAULTS). And they're just 'shifted', which makes it very efficient, and even very easy to unload again. So, they are differences to apply if this host with the file (@-prefixed) is selected.

They get automatically loaded, and reside beneath the other counter files.

Note To check these configuration (difference) files, the regular --config / -c command line parameter must be extended with at least one {host,override}-name or even glob(s). Checks one or more of this per-host config files.

Hosts with their own configuration (difference) overwrites have their own mark in the last Configuration column, where the first (bold) integer indicates how many real, valid configuration items it has, the second value (after /) shows how many items there are available in the host config file (as usual a JSON file with @ prefix char).

Warning The configuration files are encoded in the JSON format (and don't need to hold the whole set of available configuration items)! _{and yes, this is a warning.. xD~}

Relative paths

Absolute paths work as usual. But relative paths are used here in two ways.

If you define your path, log or fonts as simple directory name like count or count/, it'll be resolved from the location of your count.php script (using __DIR__). But to define this relative to your current working directory, you've to define those paths with starting ./ (it's where the script gets called; maybe as symbolic link or by defining a path via e.g. php ./php/count.php).

Note ../ is relative to the __DIR__, unlike ./! If you also want to make this relative to the current working directory $PWD, try ./../.

Colors

Supported formats are:

argb() (with 3x (0-255) and 1x (0.0-1.0));
rgb() (with 3x (0-255));
(comma separated) (list of 3x (0-255) and optionally 1x (0.0-1.0));
# hex color strings (w/ and w/o # prefix, with a length of one of: [ 3, 4, 6, 8 ]);

Note Above formats don't need to be defined exactly (by their names or the # hex char). The lengths are enough to determine which type it is. So just set a list of numbers or any hexadecimal notation.

Radix/Base

The radix configuration should be an Integer between 2 and 36. Default is, of course, 10! :)~

But it's worth to mention that this parameter can also be changed in the $_GET[]-URL with which this script can (optionally) be called. Just use the ?radix=10 (here with it's default value, if not defined otherwise in the radix setting mentioned here above).

Automatical file creation

This is the auto setting.

By default up to 32 value files will automatically be created, if not existing for a host. With overridden host this setting is also overwritten: true if override setting or $_host is a String, and false in all other cases.

Note If amount of value files exceeds this limit, or if set to false, you can easily initialize (or change..) these files via the --set / -s <host[=0][, ... ]> parameter in CLI mode, with optional value (integer) for each host (after = equal sign). But if value is unspecified, it defaults to 0.

Additionally, the limit setting is also used for a 'hard' maximum, even if 'auto' integer is greater or without real (int) limit!

Warning To (temporarily) disable the whole counting unit, set auto = null. ;)~

Modes

Some of the modes are as follows. And they can partially be combined as well!

Text mode

If allowed by the configuration text, you can also draw a regular text beneath the counter values or smth.

This feature is mostly there as I wanted to secure up mail addresses, e.g.. so without HTML code no (regular...) crawler or bot will be able to automatically grep such addresses. This is the main reason for this feature.

... but it's also possible to draw any regular text, if it's within the configured maximum character count (which is by default set to 32, or 64 if text setting is set to true.. false or <=0 disables it).

Note The counter will also count in this mode, if called without ?readonly / ?ro parameter.

Readonly mode

You can use the script as usual, but pass ?ro. That will only return/draw the current value without writing any files or cookies. The value is not changed then. So one can view it without access to the file system or the CLI mode.

Some functions won't be declared here, etc., just for more runtime performance and resource reasons.

Drawing mode

By using ?draw, if drawing setting is enabled, the output will not be text/plain (or whatever you define in content), but image/png or image/jpeg, so you can embed the counted value in <img>.

Please take a look at the Drawing section.

Zero mode

The ?zero should be set instead of ?draw, just to draw an 'empty' (1px) <img>. If not defined otherwise, it'll count invisible this way. :)~

Hide mode

By setting hide to true, an integer or a string, the string will be shown instead of the real count value. This feature is there for private couting, without letting the users known how much visitors you already had.

true is for a random value in the maximum range (see getrandmax()), an integer limits this value to a maximum.

Beware: if you really want to hide these values, please also create the .htaccess w/ Deny from all in your path directory!

Test mode

With ?test there will nothing be counted, and the output (can also be combined with ?draw) will be a random integer value.

CLI mode

This is the command line (interface) mode (just take a look at the screenshot on top of this README.md..).

Here you can also test your configuration's validity by running the script with --config / -c [*] parameter.

Calling this script without any parameters will show the currently counted values (and more). Otherwise just take a look at the sub section The argument vector below, or/and look at the section Operations, to understand how you can manage your whole count/ directory better.

And if you need help, don't be shy and call this script with --help / -h parameter!

Note The output of long lists is, by default, limited to 40 entries/rows. If you want to omit this, add the --lines / -n parameter. Optionally is even an integer possible, to directly set the amount of maximum rows used (even if there'll be usually a prompt to ask you for more or less..).

Note There's also the parameter --no-ansi / -N to switch off ANSI escape sequences! This is mentioned for terminals which don't support colors and styles this way.. by default it's true.

Wrapper script

In the past you had to call php count.php manually (as a shebang isn't possible with a web server script, due to the header..). Now I've added a script count.sh`, which will wrap this for you, and also argue with any parameters defined. Just use this helper script in the command line, please!

ANSI Escape Sequences

I'm using ANSI Escape Sequences, for styling and coloring the text in a console. For the best support (that every terminal, that implement these sequences), I've decided to only use the most rudimentary sequences, so only some basic styles (underline, bold, etc.) and only 4-bit colors (so only max. 8 real colors).

To globally disable these sequences, either use the define('KEKSE_ANSI', true) on top of the script, or (even better) just call the script with the (optional) parameter --no-ansi / -N!

Warning As I'm using these sequences plus the printf() function (etc.), I also implemented my own \kekse\strlen() function, plus \kekse\less(), where these sequences are being filtered out!

Note I also own a much better implementation of more than just these basic sequences, but in JavaScript: see my lib.js / Library.js; the real file path is located in this path: lib.js/tty/ansi.js.

List output limit

If you're using many hosts or many files are affected or smth. like this, I've also integrated a limitation of lines/rows outputted in the console. So if there are more than 40 (default) rows/lines to output, you're asked if you want to also show the rest of the list, or the output is stopped (w/ comment).

You can globally disable this behavior by changing the define('KEKSE_LIMIT_TTY', 40) (or even KEKSE_LIMIT_TTY_PROMPT to disable the question meantioned above), or (better) just call this script with either pure --lines / -n (to disable the limit), or define another limit by passing it to this parameter.

Note You can pass it by either --lines (int) or --lines=(int) (same with -n).

The argument vector

The following parameters are the main CLI functions.

Note They can't be combined! .. first occurence 'counts'. ;)~

Warning Parameters marked with ⚠️ are functions with 'hard' data write operations! .. to learn how to use these functions (to handle the whole count/ base directory), scroll down to the Operations section!

Here's the list of all the parameters/functions:

..	Short	Long	Description
	`-?`	`--help`	Shows the link to this website..
	`-V`	`--version`	Print current script's version.
	`-W`	`--website`	Print URL to this project page (on github.com atm.)
	`-C`	`--copyright`	Shows the author of this script. /me ..
	`-I`	`--info`	All the above infos at once
	`-c`	`--config` [*]	Verify DEFAULT or, by arguments, per-user configurations
	`-v`	`--values` [*]	Shows all vales and more.
⚠️	`-y`	`--sync` [*]	Same as above, but with cache synchronization..
⚠️	`-l`	`--clean` [*]	*Clean all outdated* (only!) cache items**
⚠️	`-p`	`--purge` [*]	Delete the cache(s) for all or specified hosts.
⚠️	`-r`	`--remove` [*]	Totally remove any host (all, or by arguments)
⚠️	`-z`	`--sanitize`	Delete file rests, which don't fit into the regular file scheme
⚠️	`-s`	`--set` <...>	Sets (optional) value for the defined host(s) [without value it's (0) by default]
	`-f`	`--fonts` [*]	Available fonts for drawing `<img>`. Globs allowed.
	`-t`	`--types`	Available image types for drawing output.
	`-h`	`--hashes`	Available algorithms for `hash` config.
	`-e`	`--errors`	Counts the error log lines.
	`-u`	`--unlog`	Deletes the whole error log file.

Additional arguments within [] are optional (and most do support GLOBs), and those within <> are required ones. Most * arguments can be defined multiple times, for more hosts, e.g.

As hint for myself I've saved glob.txt in this repository.

Warning Using globs requires quoting or escaping most times, as most shells will try to directly resolve them.. if it works sometimes, it's just because the shell didn't find any match (then the original glob is being encoded 'as is').

Warning When printing a list of files to delete or smth. like this, they require console rows/lines, of course. Some lists could be 'too long', so we limit their output to KEKSE_TTY_LIMIT rows/lines. If you need to see all list items, use the additional parameter --lines / -n. Then the whole list is being outputted.

Note The --config / -c [*] can also have optional host(/override) arguments (also globs), to not check the whole default/global configuration, but the overrided ones (by a per-host config overwrite).

Modifiers

These are the optional modifiers, mostly for specific functions (listed above). So they're not calling a function, they modify their behavior!

Short	Long	Related function	Description
`-n`	`--lines`	(*)	Disables limitation on outputted lines or set specific value (optional argument)
`-N`	`--no-ansi`	(*)	To disable the ANSI escape sequences, e.g. in 'broken' terminals, etc..
`-g`	`--config`	`--remove`	Will also remove the per-host configuration files (safed by default)
`-w`	`--without-values`	`--sanitize`, `--clean`	All host files are being deleted, if no corresponding value file is available

Note The --lines / -n modifies output of 'many' functions, whereas the others are for only one function (see 3rd column)!

Operations

This section explains the most important operations on the file system storage.

Warning Any file deletion needs to be confirmed by you, after counting (maybe even listing) the files which would be deleted. There'll appear a question, where you have to type in y[es] or n[o].

Note Any of these operations (but --sanitize / -z) can optionally be argued with one or more target hosts, and they can also be GLOBs (but think about escaping or quoting them), like also --fonts / -f.

Note NONE of the deleting functions will delete .htaccess files, so the others defined in KEKSE_KEEP*!

File Scheme

Note First it's essential to explain you the Scheme of file system items for this counter. Then, in the following sub sections you'll see exactly what happens why..

So, there are four elementary file types (for which I'm using two define() each: KEKSE_COUNTER_), as follows:

Prefix Char	Type	Meaning / Description
`~`	File	The counted values itself are being stored here (integers)
`+`	Directory	(If `server` is enabled) It'll contain every IP or their Hash as one file each; containing (integer) timestamps
`-`	File	(If `server` is enabled) These are caches to store the amount of real cache files per `+`
`@`	File	Somehow an exception.. just JSON files with difference configuration, each one for a host/override

Synchronization

--sync / -y function: Is a special case of the --values / -v function (so after regular showing all the values the sync routine starts). Will synchronize the cache files with the cache directories! Nothing else, so in case of out-of-synced cache files they're the only ones which get changed!

Optional parameter(s): Host/Override names or globs (to match for hosts).

Warning: As exception: if cache directories are without any cache files, they and their cache files get totally deleted!

Cleaning

--clean / -l function: Will search for outdated (timestamp) files in the cache directories (for any or specified host(s)). They contain timestamps, and when they exist longer than the threshold setting, they can be deleted. Also see the clean setting: if not disabled, this will also happen when the script is being called by web client (so in regular counting mode), either always, or when the amount of cache files exceeded the (soft) limit in (int)clean.

Optional parameter(s): Host/Override names or globs (to match for hosts). More optional parameters are:

Short	Long	Meaning / Description
`-w`	`--without-values`	Delete `KEKSE_COUNTER_DIR` and `KEKSE_COUNTER_FILE` files if no proper `KEKSE_COUNTER_VALUE` file was found. Exception: doesn't delete `KEKSE_COUNTER_CONFIG` files!

Warning The threshold is maybe not set to an integer above zero, in this case the whole cache directories will be deleted.

Warning It's important to know that a per-host config overwrite may define an additional threshold time for a host. In this case this specific time will be used to check for outdated cache files!! And if it's not an integer above zero, the whole cache directory will be deleted, too.

Warning If a cache directory exist for a host/override which is not available as (~ prefixed) value file, you need to also define --without-values / -w parameter if the whole cache should also be deleted. Otherwise it'll be handled as usual.

Warning Will also delete any file in the cache directories which are no regular files.

Purging

--purge / -p function: This function deletes all the cache files and directories for selected/all hosts. So only the KEKSE_COUNTER_DIR directories, with all their timestamp files in them, plus the corresponding caching KEKSE_COUNTER_FILE files which contain the amount of timestamp files for each directory.

Optional parameter(s): Host/Override names or globs (to match for hosts).

Removing

--remove / -r function: Will delete any (real, valid) host file, except the per-host configuration overwrites. Except if the --config / -g parameter is also defined (also possible in combination with the globs or hosts/overrides). With this the configuration files to the specified or found hosts will also be deleted!

Optional parameter(s): Host/Override names or globs (to match for hosts).

Sanitizing

--sanitize / -z function: Deletes any file in the counter directory and every KEKSE_COUNTER_DIR sub directory which doesn't fit in there. Foreign files the counter doesn't need.

Optional parameter(s): Host/Override names or globs (to match for hosts). More optional parameters are:

Short	Long	Meaning / Description
`-w`	`--without-values`	Delete `KEKSE_COUNTER_DIR` and `KEKSE_COUNTER_FILE` files if no proper `COUNTER_VALUE` file was found. Exception: doesn't delete `KEKSE_COUNTER_CONFIG` files!

Warning This also holds for the cache directories, which will also be inspected, so all non-regular files in there will be deleted as well!

Exports

For the count(er) implementation itself I'm using the namespace kekse\counter.

Note Namespaces used in this script are these ones:

kekse

kekse\color

kekse\counter

kekse\console

kekse\console\ansi

Note Maybe you'd like to know that enabling the KEKSE_RAW (on top of file) will export all my extensions, but without the \kekse\counter namespace, and the base counter() function also won't get called. So you can include this script to get all my following functions without the counter part itself! ;)~

Note This script only defines the KEKSE_RAW if not already defined: this way you can define it in any other PHP script which includes the kekse exports, e.g. via require_once()! :-D

The following common functions (which tend to be used also in other scripts, as they're 'abstract' and useful also in other scripts) are exported in my own kekse namespace. They could be really handy:

Function	Arguments	Description
`renderSize()`	`$_bytes`, `$_precision`	Just to convert a byte count integer to a real string with unit suffix (only base 1024 atm.)
`is_number()`	`$_item`	PHP is missing 'between' `is_int()` and `is_float()`.. as `is_numeric()` is also for Strings..
`strlen()`	`$_string`, `$_filter = false`, `$_binary = false`, `$_hidden = true`	Own version, mostly to count string length with filtered out ANSI escape sequences (or binary)!
`less()`	`$_string`, `$_binary = false`, `$_hidden = true`	Wrapper for `strlen()` w/ `$_filter = null`, to not count, but to return a filtered string
`endsWith()`	`$_haystack`, `$_needle`, `$_case_sensitive = true`	Extending `str_ends_with()` with the `$_case_sensitive` parameter (defaults to `true`
`startsWith()`	`$_haystack`, `$_needle`, `$_case_sensitive = true`	Same like above, but for `str_starts_with()`
`normalize()`	`$_path`	Implementation of path normalization (works)
`joinPath()`	`... $_args`	Combines multiple path components to a whole path string (variadic function)
`timestamp()`	`$_diff = null`	Integer: either the timestamp itself (unix seconds) or the difference to another timestamp
`removeWhiteSpaces()`	`$_string`	Removes any occurence of binary/non-printable chars and spaces (0..32, 127) .. wrapper function
`removeBinary()`	`$_string`, `$_space = false`	Same as `removeWhiteSpaces()`, but without spaces (if `$_space === false`, which is default)
`getParam()`	`$_key`, `$_numeric = false`, `$_float = true`, `$_fallback = true`	Returns a `$_GET[]` variable very secured and optionally converted (int, double, bool)
`unit()`	`$_string`, `$_float = false`, `$_null = true`	Splits into value and unit components, which so can be defined in one string only.
`color()`	`$_string`, `$_gd = null`	See Colors.. the `$_gd` argument is `true` if `extension_loaded('gd')`, `if(!bool)`
`delete()`	`$_path`, `$_depth = 0`, `$_extended = false`	Function for any file deletion! Also recursively, w/ optional (int)depth (or true/false)
`checkPath()`	`$_path`, `$_file`, `$_log_error_source = null`, (...)	Default routine to check for file existence or creation, and `chmod()` for more security
`limit()`	`$_string`, `$_length = 224` (`KEKSE_LIMIT_STRING`)	For a maximum string length. Also look at `KEKSE_LIMIT_STRING` (which is `224`, by default)
`secure()`	`$_string`, `$_lower_case = false`	See String filter: to avoid code injection or smth. similar
`secureHost()`	`$_string`	Wrapper for `secure()` with `$_lower_case = true` (as hostnames are not case sensitive, ...)
`securePath()`	`$_string`	ATM only an alias for the base `secure()` itself. But maybe it'll be improved l8rs.
`readFile()`	`$_path`, `... $_args`	Especially for reading files within a limited length.. extended version in `kekse\counter`
`writeFile()`	`$_path`, `$_value`, `... $_args`	Nearly as above; the extended `kekse\counter` version is also build up upon `securityTest()`
`readInt()`	`$_path`, `... $_args`	Uses `readFile()`, but is especially for managing the counter values or timestamp files, etc.
`writeInt()`	`$_path`, `$_int`, `... $_args`	For writing integers.. uses `writeFile()`.
`log()`	[`*`,] `$_format`, `... $_args`	(CLI feature) Write line to STDOUT, w/ or w/o EOL (or many) with non-colored `>>` prefix
`info()`	[`*`,] `$_format`, `... $_args`	(CLI feature) Write line to STDOUT, w/ or w/o EOL (or many) w/ green colored `>>` prefix
`error()`	[`*`,] `$_format`, `... $_args`	(CLI feature) Write line to STDERR, w/ or w/o EOL (or many) with red colored `>>` prefix
`warn()`	[`*`,] `$_format`, `... $_args`	(CLI feature) Write line to STDERR, w/ or w/o EOL (or many) w/ orange colored `>>` prefix
`debug()`	[`*`,] `$_format`, `... $_args`	(CLI feature) Write line to STDERR, w/ or w/o EOL (or many) with blue colored `>>` prefix
`prompt()`	`$_string`, `$_return = false`, `$_repeat = true`	(CLI feature) Let the user decide between `y[es]`/`n[o]`, with yellow colored `>>` prefix

.. maybe even more? Maybe some aren't always available? TODO: take a more detail look at all this...

Modules

TODO! Whenever I'm in the mood to implement this (a bigger thing..), I'm thinking about (at least):

events.php
notifications.php
statistics.php

FAQ

This section grew as I got comments on my code. And I hope for your reviews, really! Please contact me, if you would like to review my code. I don't bite, promised! xD~

# Why not using a `class`?

Just because it ain't necessary. I've just set a namespace kekse\counter, so everything is no longer in the global namespace.. that should be enough. It could even really be, that using classes would even end up in more resource consumption.. so, I think it's O.K. as it is now.. 'old skewl'! :)~

Update: I admit it could be better to use multiple files (which I wanted to avoid in this version), maybe with classes. The current code loads certain parts only if necessary, but it could be even better to distribute the code over many files, so a require_once would reduce the overhead to a maximum...

# Installation via Composer?

I'm pretty sure there's no real 'installation' necessary here.. additionally, there are also no real dependencies which the 'Composer' would need to install.

A minimum installation is described above, in the Installation section, jfyi!

# Isn't this all a little big for such a script?

At least I've heard this from a reviewer..

Don't panic! The runtime will never use nor even define all the functions etc.. their existence is reduced by some if() and as some are sub-functions of other functions, and also by evaluating a minimum first, to maybe return earlier; etc..

I promise not to bloat everything too much; it's just a matter of fact that this script has many features and is highly configurable.. nevertheless there are some optimizations etc., so it really doesn't consume that much cpu time or memory.

Note As of v5.2.0 there are 'only' 10.364 code lines left (and there are nearly no comments).

If you find more possible optimizations, don't be shy and contact me! I'd be really happy. :-)

TODO

The output of the CLI Mode (at least the counter values) should be exportable als JSON!

The original version

The original version was a very tiny script as little helping hand for my web projects. It rised a lot - see for yourself! :)~

Copyright and License

The Copyright is (c) Sebastian Kucharczyk, and it's licensed under the MIT (also known as 'X' or 'X11' license).

Name		Name	Last commit message	Last commit date
Latest commit History 779 Commits
count		count
docs		docs
fonts		fonts
modules		modules
php		php
sh		sh
.gitignore		.gitignore
.keep		.keep
COPYRIGHT.txt		COPYRIGHT.txt
LICENSE.txt		LICENSE.txt
NotoEmoji.ttf		NotoEmoji.ttf
README.md		README.md
count.php		count.php
count.sh		count.sh
favicon.512px.png		favicon.512px.png
favicon.png		favicon.png

License

kekse1/count.php

Folders and files

Latest commit

History

Repository files navigation

Index

Updated

Installation

Dependencies

Screenshots

Directory structure

Details

text/plain

Image

Security

Storage

Server and/or Client

Refresh

Override

Static mode

Overwrites

Cleaning

Privacy

Errors

Log to file

String filter

FQDN's

Security test

Drawing

Parameters

Explaination

Dependencies

Libraries

Fonts

Configuration

No more constants.

Per-host config overwrite

Relative paths

Colors

Radix/Base

Automatical file creation

Modes

Text mode

Readonly mode

Drawing mode

Zero mode

Hide mode

Test mode

CLI mode

Wrapper script

ANSI Escape Sequences

List output limit

The argument vector

Modifiers

Operations

File Scheme

Synchronization

Cleaning

Purging

Removing

Sanitizing

Exports

Modules

FAQ

# Why not using a class?

# Installation via Composer?

# Isn't this all a little big for such a script?

TODO

The original version

Copyright and License

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

# Why not using a `class`?

Packages