Skip to content

Commit a3b9a41

Browse files
a19836a19836
committed
updating local files
0 parents  commit a3b9a41

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

48 files changed

+4764
-0
lines changed

‎LICENSE.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
This is **multi-licensed**. You may choose to use it under **one of the following licenses**:
2+
3+
- **BSD 3-Clause License** or
4+
- **Apache License 2.0** or
5+
- **GNU LGPL v3** or
6+
- **[HLNC License](http://bloxtor.com/LICENSE_HLNC.md)**
7+
8+
Select the license that best fits your needs.
9+
10+
**This is 100% open to your needs!**
11+
12+
© 2025 [Bloxtor](http://bloxtor.com) and [Joao Pinto](http://jplpinto.com)

‎README.md‎

Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
# PHP Cache Lib
2+
3+
> Original Repos:
4+
> - PHP Cache Lib: https://github.com/a19836/phpcachelib/
5+
> - Bloxtor: https://github.com/a19836/bloxtor/
6+
7+
## Overview
8+
9+
**PHP Cache Lib** is a simple cache library designed for caching contents, objects, arrays, strings, and more.
10+
It offers flexible backend support, allowing you to cache your data using **file system, MongoDB, Memcache, or Redis**.
11+
12+
To see a working example, open [index.php](index.php) on your server.
13+
14+
---
15+
16+
## Handlers
17+
18+
### User Cache Handler
19+
20+
To be used to cache content (objects/arrays/string/etc) in a specific folder/place, regardless of the underlying storage engine (file system, MongoDB, MemCache, Redis etc.).
21+
All cached content can be **serialized** or saved as **plain** content.
22+
23+
All methods are **based in the file name argument**, where the cached file path is created from the **root path defined before** and the correspondent file name.
24+
Note that if root path, defined before, does not exist, it will be created automatically.
25+
26+
Also if you cache to many files, you can reach the maximum inodes limit of your OS. In this case you should use the ServiceCacheHandler instead, because it takes care this issue.
27+
Note that cache deletion based in regex is not allowed! For this case please use the ServiceCacheHandler instead.
28+
29+
Main available methods:
30+
31+
| Method | Description |
32+
| :--- | :--- |
33+
| `read($file_name)` | **Retrieves** the cached data associated with the given file name. |
34+
| `write($file_name, $data)` | **Writes** the provided data to the cache using the specified file name as the key. |
35+
| `isValid($file_name)` | **Checks** if the cached entry exists *and* has not expired (is still valid based on its Time-To-Live). |
36+
| `exists($file_name)` | **Checks** if a cache entry physically exists for the given file name. |
37+
| `delete($file_name)` | **Removes** the cached entry associated with the given file name. |
38+
39+
### Serialized Cache Handler
40+
41+
To be used to cache content (objects/arrays/string/etc) in a specific file path, regardless of the underlying storage engine (file system, MongoDB, MemCache, Redis etc.).
42+
All cached content is **serialized**.
43+
44+
All methods are based in the **full file path argument**, where the cached file path is this path - without any kind of path treatment.
45+
Note that for the **file system engine, the parent directory of the file path must exists**!
46+
47+
Also if you cache to many files, you can reach the maximum inodes limit of your OS. In this case you should use the ServiceCacheHandler instead, because it takes care this issue.
48+
Note that cache deletion based in regex is not allowed! For this case please use the ServiceCacheHandler instead.
49+
50+
Main available methods:
51+
52+
| Method | Description |
53+
| :--- | :--- |
54+
| `getCache($file_path)` | **Retrieves** the cached data stored at the given `$file_path` (which acts as the unique key). |
55+
| `setCache($file_path, $data)` | **Writes** the provided `$data` to the cache, using the `$file_path` as the storage identifier. |
56+
| `isCacheValid($file_path)` | **Checks** if the cache entry at `$file_path` exists and is still valid (not expired). |
57+
| `deleteCache($file_path)` | **Removes** the cached entry associated with the `$file_path`. |
58+
59+
### Service Cache Handler
60+
61+
To be used to cache content (objects/arrays/string/etc), regardless of the underlying storage engine (file system, MongoDB, MemCache, Redis etc.), that may have other objects related, and everytime that we create a new cache, it automatically disable the related cached objects.
62+
Is used for caching **services** or complex data structures, often utilizing a `$prefix` for categorization and supporting **related keys** for complex invalidation.
63+
All cached content can be **serialized** or saved as **plain** content.
64+
65+
All methods are based in the **prefix and key arguments**, where the cached file path is created from the **root path defined before** and the prefix and key.
66+
Note that the prefix is a string that could be a relative folder path.
67+
Note that if the root path does not exist, it will be created automatically.
68+
69+
The cached objects are saved inside of **multiple folders** (inside of the root path) to **avoid to reach the maximum inodes limit** of the OS. This handlers take care of this issue, so you don't need to worry about it.
70+
**Deletion based in regex and other conditions** are also allowed!
71+
72+
Although, is not allowed to get cached objects based in regex or other conditions, the idea is to create this feature in the future.
73+
74+
Main available methods:
75+
76+
| Method | Description |
77+
| :--- | :--- |
78+
| `create($prefix, $key, $result, $type = false)` | **Creates** a new cache entry for a service using a `$prefix` and `$key`. |
79+
| `addServiceToRelatedKeysToDelete(...)` | **Adds** the current service (`$prefix`, `$key`) to a list of services to be deleted when one of the parents are invalidated. |
80+
| `deleteAll($prefix, $type = false)` | **Removes all** cache entries that fall under the specified `$prefix`. |
81+
| `delete($prefix, $key, $settings = array())` | **Removes** a specific cache entry defined by `$prefix` and `$key`. It can also be used to delete related services. See a livde example [here](examples/service_cache_with_relations.php). |
82+
| `get($prefix, $key, $type = false)` | **Retrieves** the cached data for the service specified by `$prefix` and `$key`. |
83+
| `isValid($prefix, $key, $ttl = false, $type = false)` | **Checks** if the cached service entry is currently valid (exists and has not expired). |
84+
85+
---
86+
87+
## Usage
88+
89+
The library provides different handlers for various caching needs and engines.
90+
91+
### 1. User Cache (File System)
92+
93+
This sample demonstrates how to use the `FileSystemUserCacheHandler` for basic data caching with an unique file name.
94+
95+
```php
96+
include_once __DIR__ . "/lib/app.php";
97+
include_once get_lib("cache.user.filesystem.FileSystemUserCacheHandler");
98+
99+
$CacheHandler = new FileSystemUserCacheHandler();
100+
$CacheHandler->setRootPath( sys_get_temp_dir() . "/cache/user/" );
101+
$CacheHandler->config(60, true); // 60 seconds of cache ttl
102+
103+
$file_name = "my_cached_file_name"; // Must be unique.
104+
105+
// Get cached contents
106+
if ($CacheHandler->isValid($file_name))
107+
$data = $CacheHandler->read($file_name);
108+
else { // Otherwise create cache for next time
109+
$data = array("foo" => "bar", "bar" => "foo"); // Contents to cache
110+
$CacheHandler->write($file_name, $data);
111+
}
112+
113+
// Then use $data...
114+
```
115+
116+
### 2. Serialized Cache (File System)
117+
118+
This sample uses `FileSystemXmlSettingsCacheHandler` and requires preparing the cache folder beforehand.
119+
120+
```php
121+
include_once __DIR__ . "/lib/app.php";
122+
include_once get_lib("cache.xmlsettings.filesystem.FileSystemXmlSettingsCacheHandler");
123+
124+
$CacheHandler = new FileSystemXmlSettingsCacheHandler();
125+
$CacheHandler->setCacheTTL(60); // 60 seconds of cache ttl
126+
127+
// Prepare cache folder - must create the cached folder first
128+
$root_path = sys_get_temp_dir() . "/cache/xml_settings/";
129+
130+
if (!is_dir($root_path))
131+
mkdir($root_path, 0755, true);
132+
133+
// Set file path to be cached
134+
$file_path = $root_path . "my_cached_file_name"; // Must be unique.
135+
136+
// Get cached contents
137+
if ($CacheHandler->isCacheValid($file_path))
138+
$cached_data = $CacheHandler->getCache($file_path);
139+
else { // Otherwise create cache for next time
140+
$data = array("foo" => "bar", "bar" => "foo"); // Contents to cache
141+
$CacheHandler->setCache($file_path, $data); // setCache($file_path, $data, $renew_data = false)
142+
}
143+
144+
// Then use $data...
145+
```
146+
147+
### 3. Serialized Cache (MongoDB)
148+
149+
This sample shows how to integrate with MongoDB using `MongoDBXmlSettingsCacheHandler`.
150+
151+
```php
152+
include_once __DIR__ . "/lib/app.php";
153+
include_once get_lib("mongodb.MongoDBHandler");
154+
include_once get_lib("cache.xmlsettings.mongodb.MongoDBXmlSettingsCacheHandler");
155+
156+
$MongoDBHandler = new MongoDBHandler();
157+
$MongoDBHandler->connect("192.168.1.68", "my_cache_db", "mdbu", "mdbp", 8097);
158+
159+
$CacheHandler = new MongoDBXmlSettingsCacheHandler();
160+
$CacheHandler->setMongoDBHandler($MongoDBHandler);
161+
$CacheHandler->setCacheTTL(60); // 60 seconds of cache ttl
162+
163+
// Set file path to be cached
164+
$file_path = "my_cached_file_name"; // Must be unique.
165+
166+
// Get cached contents
167+
if ($CacheHandler->isCacheValid($file_path))
168+
$cached_data = $CacheHandler->getCache($file_path);
169+
else { // Otherwise create cache for next time
170+
$data = array("foo" => "bar", "bar" => "foo"); // Contents to cache
171+
$CacheHandler->setCache($file_path, $data); // setCache($file_path, $data, $renew_data = false)
172+
}
173+
174+
// Then use $data...
175+
```
176+
177+
### 4. Service Cache (Memcache)
178+
179+
This sample utilizes `MemcacheServiceCacheHandler` and introduces concepts like prefixes and service relations.
180+
181+
```php
182+
include_once __DIR__ . "/lib/app.php";
183+
include_once get_lib("cache.service.memcache.MemcacheServiceCacheHandler");
184+
185+
$MemcacheHandler = new MemcacheHandler();
186+
$MemcacheHandler->connect("192.168.1.68", 8090);
187+
188+
$CacheHandler = new MemcacheServiceCacheHandler();
189+
$CacheHandler->setMemcacheHandler($MemcacheHandler);
190+
$CacheHandler->setRootPath("service_cache/"); // if file system handler: sys_get_temp_dir() . "/cache/service_cache/";
191+
$CacheHandler->setDefaultTTL(60); // 60 seconds of cache ttl
192+
$CacheHandler->setDefaultType("php"); // type can be: "php" or "text"
193+
194+
$prefix = "foo/bar/"; // optional
195+
$key = "my_data_key"; // Must be unique for each cached service.
196+
197+
// Get cached contents
198+
if ($CacheHandler->isValid($prefix, $key)) // isValid($prefix, $key, $ttl = false, $type = false)
199+
$data = $CacheHandler->get($prefix, $key); // get($prefix, $key, $type = false)
200+
else { // Otherwise create cache for next time
201+
$data = array("foo" => "bar", "bar" => "foo"); // Contents to cache
202+
$CacheHandler->create($prefix, $key, $data); // create($prefix, $key, $data, $type = false)
203+
}
204+
205+
// Then use $data...
206+
207+
// Note: You can also relate services to other services and then delete those related services.
208+
// For more details, check the file examples/service_cache_with_relations.php
209+
```
210+
211+
### 5. Cache (Redis)
212+
213+
A Redis usage sample is planned.
214+
215+
```php
216+
// TODO: Redis usage sample
217+
```
218+
219+
---
220+
221+
## Further Examples
222+
223+
The repository includes more detailed examples to guide your implementation:
224+
- [User Cache Example](examples/user_cache.php)
225+
- [Serialized Cache Example](examples/xml_settings_cache.php)
226+
- [Service Cache Example without Related Services](examples/service_cache.php)
227+
- [Service Cache Example with Related Services](examples/service_cache_with_relations.php)
228+

‎examples/config.php‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
<?php
2+
/*
3+
* Copyright (c) 2025 Bloxtor (http://bloxtor.com) and Joao Pinto (http://jplpinto.com)
4+
*
5+
* Multi-licensed: BSD 3-Clause | Apache 2.0 | GNU LGPL v3 | HLNC License (http://bloxtor.com/LICENSE_HLNC.md)
6+
* Choose one license that best fits your needs.
7+
*
8+
* Original PHP Cache Lib Repo: https://github.com/a19836/phpcachelib/
9+
* Original Bloxtor Repo: https://github.com/a19836/bloxtor
10+
*
11+
* YOU ARE NOT AUTHORIZED TO MODIFY OR REMOVE ANY PART OF THIS NOTICE!
12+
*/
13+
14+
include_once dirname(__DIR__) . "/lib/app.php";
15+
16+
$type = ""; //empty, mongodb, memcache or redis
17+
18+
switch($type) {
19+
case "memcache":
20+
include_once get_lib("memcache.MemcacheHandler");
21+
22+
$MemcacheHandler = new MemcacheHandler();
23+
$MemcacheHandler->connect($host = "", $port = "", $timeout = null);
24+
break;
25+
26+
case "mongodb":
27+
include_once get_lib("mongodb.MongoDBHandler");
28+
29+
$MongoDBHandler = new MongoDBHandler();
30+
$MongoDBHandler->connect($host = "", $db_name = "", $username = "", $password = "", $port = "", $options = null);
31+
break;
32+
33+
case "redis":
34+
//TODO
35+
break;
36+
}
37+
38+
//SET SOME STYLING
39+
$style = '<style>
40+
select {background:#eee; border:1px solid #ccc; border-radius:3px; padding:3px 2px;}
41+
h1 {margin-bottom:0; text-align:center;}
42+
h5 {font-size:1em; margin:40px 0 0; font-weight:bold;}
43+
p {margin:0 0 20px; text-align:center;}
44+
45+
.note {text-align:center;}
46+
.note span {text-align:center; margin:0 20px 20px; padding:10px; color:#aaa; border:1px solid #ccc; background:#eee; display:inline-block; border-radius:3px;}
47+
48+
.code {display:block; margin:10px 0; padding:0; background:#eee; border:1px solid #ccc; border-radius:3px; position:relative;}
49+
.code:before {content:"php"; position:absolute; top:5px; left:5px; display:block; font-size:80%; opacity:.5;}
50+
.code textarea {width:100%; height:300px; padding:30px 10px 10px; display:inline-block; background:transparent; border:0; resize:vertical; font-family:monospace;}
51+
52+
.test {display:block; margin:20px 0; padding:20px; background:#eee; border:1px solid #ccc; border-radius:3px; position:relative;}
53+
.test:before {content:"test"; position:absolute; top:5px; left:5px; display:block; font-size:80%; opacity:.5;}
54+
.test h4 {position:absolute; top:5px; right:5px; font-size:.9em; margin:0; font-size:80%; opacity:.5;}
55+
.test ul {margin:0;}
56+
</style>';
57+
58+
//SET SOME FUNCTIONS
59+
function printCache($label, $root_path, $original_data, $cached_data) {
60+
echo '<div class="test">
61+
<h4>Start test for "' . $label . '"</h4>
62+
<div>Original Data: ' . print_r($original_data, true) . '</div>
63+
<div>Cached Data: ' . print_r($cached_data, true) . '</div>
64+
<div>Cached Files:';
65+
66+
echo printCachedFolder($root_path);
67+
68+
echo '</div>
69+
</div>';
70+
}
71+
72+
function printCachedFolder($path) {
73+
if ($path && is_dir($path)) {
74+
$files = array_diff(scandir($path), array('.', '..'));
75+
76+
echo '<ul>';
77+
78+
if ($files)
79+
foreach ($files as $file) {
80+
$fp = $path . $file;
81+
82+
echo '<li>' . $file . ': ';
83+
84+
if (is_dir($fp))
85+
echo printCachedFolder($fp . "/");
86+
else
87+
echo file_get_contents($fp);
88+
89+
echo '</li>';
90+
}
91+
else
92+
echo '<li>No files!</li>';
93+
94+
echo '</ul>';
95+
}
96+
else if ($path)
97+
echo '<div>Folder "' . $path . '" does NOT exists!</div>';
98+
}
99+
?>

0 commit comments

Comments
 (0)