PHP Classes

PHP Circular Buffer: Store values in a circular buffed array

Recommend this page to a friend!
     
  Info   Example   View files Files   Install with Composer Install with Composer   Download Download   Reputation   Support forum   Blog    
Ratings Unique User Downloads Download Rankings
Not enough user ratingsTotal: 104 All time: 9,745 This week: 66Up
Version License PHP version Categories
circular-buffer 1.0.2GNU General Publi...5.5PHP 5, Data types
Description 

Author

This class can store values in a circular buffer array.

It can keep adding values to an array with position numbers with up to a given limit.

When the array entries exceed the initial limit number, the class starts setting values from the start of the array.

Picture of Christian Vigh
  Performance   Level  
Name: Christian Vigh <contact>
Classes: 32 packages by
Country: France France
Age: 58
All time rank: 13410 in France France
Week rank: 6 Up1 in France France Up
Innovation award
Innovation award
Nominee: 20x

Winner: 3x

Example

<?php
   
/***********************************************************************************************************

        The following example demonstrates the use of the CircularBuffer class.

        It first creates a circular buffer for handling 10 items, then adds 20 items to it.
        It finally displays the contents of the circular buffer, which contains only items #11 to #20 (the
        items #1 to #10 have been overridden).

     ***********************************************************************************************************/
   
require ( 'CircularBuffer.phpclass' ) ;

    if (
php_sapi_name ( ) != 'cli' )
        echo (
"<pre>" ) ;

   
// Create a circular buffer of 10 elements
   
$buffer = new CircularBuffer ( 10 ) ;

   
// Fill it with 20 items
   
for ( $i = 0 ; $i < 20 ; $i ++ )
       
$buffer [] = "Item #" . ( $i + 1 ) ;

   
// Print the items contained in the circular buffer (this will show the string "Item #11" through "Item #20"
   
echo "*** Contents of the circular buffer :\n" ;

    foreach (
$buffer as $item )
        echo
"\t$item\n" ;

    echo
"*** Number of items in the circular buffer : " . count ( $buffer ) . "\n" ;
    echo
"*** Contents of the 1st circular buffer item : {$buffer [0]}\n" ;


Details

INTRODUCTION

The CircularBuffer class implements a circular buffer, ie a buffer that can store a limited number of items. If you add items that exceed the capacity of the circular buffer, then the older items will be "forgotten" to leave room to the ones you want to add.

Circular buffers are often used when you have to face the following trade-offs :

  • The amount of memory you are authorized to use is limited
  • As time goes by, you can accept to discard some of the oldest data you're storing into the circular buffer

    ## Creating a circular buffer ##

Creating a circular buffer is easy ; just fix yourself a limit on the number of items you want to store :

$buffer 	=  new CircularBuffer ( 1000 ) ; 	// The circular buffer will be able to store at most 1000 elements

Adding items to a circular buffer

Adding items is easy ; just use the circular buffer as an array to append your latest items :

$buffer [] 	=  "This is a log message" ;

Retrieving items

Since the CircularBuffer class implements the ArrayAccess, Coutable and IteratorAggregate interface, you can perform the following operations :

  • Retrieve the number of items present in the buffer using the PHP count() function
  • Using the array notation to retrieve a particular element (eg : $buffer [0]). Note that index 0 will always return you the oldest element in the circular buffer, if it's not empty)
  • Enumerate the items currently stored in the circular buffer using a foreach construct.

REFERENCE

Constructor

The CircularBuffer class constructor has 3 different signatures, described in the following sections :

$buffer = new CircularBuffer ( $size ) ;

Creates a circular buffer that is able to store $size elements.

$buffer = new CircularBuffer ( $array ) ;

Creates a circular buffer and initializes it with the contents of $array.

The size of the circular buffer will be the size of the specified array.

$buffer = new CircularBuffer ( $array, $size ) ;

Creates a circular buffer and initializes it with the contents of $array.

The circular buffer will have $size size elements. If $size is less than the number of items in $array, the circular buffer will be initialized with its first $size elements. If $size is greater, then emty elements will be added to the circular buffer.

$buffer -> Reset ( ) ;

Empties the contents of the circular buffer.


  Files folder image Files (5)  
File Role Description
Plain text file CircularBuffer.phpclass Class Class source
Accessible without login Plain text file example.php Example Example script
Accessible without login Plain text file LICENSE Lic. License text
Accessible without login Plain text file NOTICE Data Auxiliary data
Accessible without login Plain text file README.md Doc. Documentation

The PHP Classes site has supported package installation using the Composer tool since 2013, as you may verify by reading this instructions page.
Install with Composer Install with Composer
 Version Control Unique User Downloads Download Rankings  
 100%
Total:104
This week:0
All time:9,745
This week:66Up