root/fBuffer.php

Class Resources

Revision 448, 6.3 kB (checked in by wbond, 1 year ago)

Updated copyright notices and licenses to use Will instead of William, corrected a few dates

LineHide Line Numbers
1 <?php
2 /**
3  * Provides a single, simplified interface for [http://php.net/outcontrol output buffering] to prevent nested buffering issues and provide a more logical API
4  *
5  * @copyright  Copyright (c) 2008 Will Bond
6  * @author     Will Bond [wb] <will@flourishlib.com>
7  * @license    http://flourishlib.com/license
8  *
9  * @package    Flourish
10  * @link       http://flourishlib.com/fBuffer
11  *
12  * @version    1.0.0b
13  * @changes    1.0.0b  The initial implementation [wb, 2008-03-16]
14  */
15 class fBuffer
16 {
17     // The following constants allow for nice looking callbacks to static methods
18     const erase        = 'fBuffer::erase';
19     const get          = 'fBuffer::get';
20     const isStarted    = 'fBuffer::isStarted';
21     const replace      = 'fBuffer::replace';
22     const reset        = 'fBuffer::reset';
23     const start        = 'fBuffer::start';
24     const startCapture = 'fBuffer::startCapture';
25     const stop         = 'fBuffer::stop';
26     const stopCapture  = 'fBuffer::stopCapture';
27    
28    
29     /**
30     * If output capturing is currently active
31     *
32     * @var boolean
33     */
34     static private $capturing = FALSE;
35    
36     /**
37     * If output buffering has been started
38     *
39     * @var integer
40     */
41     static private $started = FALSE;
42    
43    
44     /**
45     * Erases the output buffer
46     *
47     * @return void
48     */
49     static public function erase()
50     {
51         if (!self::$started) {
52             throw new fProgrammerException(
53                 'The output buffer can not be erased since output buffering has not been started'
54             );
55         }
56         if (self::$capturing) {
57             throw new fProgrammerException(
58                 'Output capturing is currently active and it must be stopped before the buffer can be erased'
59             );
60         }
61         ob_clean();
62     }
63    
64    
65     /**
66     * Returns the contents of output buffer
67     *
68     * @return string  The contents of the output buffer
69     */
70     static public function get()
71     {
72         if (!self::$started) {
73             throw new fProgrammerException(
74                 'The output buffer can not be retrieved because it has not been started'
75             );
76         }
77         if (self::$capturing) {
78             throw new fProgrammerException(
79                 'Output capturing is currently active and it must be stopped before the buffer can be retrieved'
80             );
81         }
82         return ob_get_contents();
83     }
84    
85    
86     /**
87     * Checks if buffering has been started
88     *
89     * @return boolean  If buffering has been started
90     */
91     static public function isStarted()
92     {
93         return self::$started;
94     }
95    
96    
97     /**
98     * Replaces a value in the output buffer
99     *
100     * @param  string $find     The string to find
101     * @param  string $replace  The string to replace
102     * @return void
103     */
104     static public function replace($find, $replace)
105     {
106         if (!self::$started) {
107             throw new fProgrammerException(
108                 'A replacement can not be made since output buffering has not been started'
109             );
110         }
111         if (self::$capturing) {
112             throw new fProgrammerException(
113                 'Output capturing is currently active and it must be stopped before a replacement can be made'
114             );
115         }
116        
117         // ob_get_clean() actually turns off output buffering, so we do it the long way
118         $contents = ob_get_contents();
119         ob_clean();
120        
121         echo str_replace($find, $replace, $contents);
122     }
123    
124    
125     /**
126     * Resets the configuration and buffer of the class
127     *
128     * @internal
129      *
130     * @return void
131     */
132     static public function reset()
133     {
134         if (self::$capturing) {
135             self::stopCapture();   
136         }
137         if (self::$started) {
138             self::erase();
139             self::stop();   
140         }
141     }
142    
143    
144     /**
145     * Starts output buffering
146     *
147     * @return void
148     */
149     static public function start()
150     {
151         if (self::$started) {
152             throw new fProgrammerException(
153                 'Output buffering has already been started'
154             );
155         }
156         if (self::$capturing) {
157             throw new fProgrammerException(
158                 'Output capturing is currently active and it must be stopped before the buffering can be started'
159             );
160         }
161         ob_start();
162         self::$started = TRUE;
163     }
164    
165    
166     /**
167     * Starts capturing output, should be used with ::stopCapture() to grab output from code that does not offer an option of returning a value instead of outputting it
168     *
169     * @return void
170     */
171     static public function startCapture()
172     {
173         if (self::$capturing) {
174             throw new fProgrammerException(
175                 'Output capturing has already been started'
176             );
177         }
178         ob_start();
179         self::$capturing = TRUE;
180     }
181    
182    
183     /**
184     * Stops output buffering, flushing everything to the browser
185     *
186     * @return void
187     */
188     static public function stop()
189     {
190         if (!self::$started) {
191             throw new fProgrammerException(
192                 'Output buffering can not be stopped since it has not been started'
193             );
194         }
195         if (self::$capturing) {
196             throw new fProgrammerException(
197                 'Output capturing is currently active and it must be stopped before buffering can be stopped'
198             );
199         }
200        
201         // Only flush if there is content to push out, otherwise
202         // we might prevent headers from being sent
203         if (ob_get_contents()) {
204             ob_end_flush();
205         } else {
206             ob_end_clean();
207         }
208        
209         self::$started = FALSE;
210     }
211    
212    
213     /**
214     * Stops capturing output, returning what was captured
215     *
216     * @return string  The captured output
217     */
218     static public function stopCapture()
219     {
220         if (!self::$capturing) {
221             throw new fProgrammerException(
222                 'Output capturing can not be stopped since it has not been started'
223             );
224         }
225         self::$capturing = FALSE;
226         return ob_get_clean();
227     }
228    
229    
230     /**
231     * Forces use as a static class
232     *
233     * @return fBuffer
234     */
235     private function __construct() { }
236 }
237  
238  
239  
240 /**
241  * Copyright (c) 2008 Will Bond <will@flourishlib.com>
242  *
243  * Permission is hereby granted, free of charge, to any person obtaining a copy
244  * of this software and associated documentation files (the "Software"), to deal
245  * in the Software without restriction, including without limitation the rights
246  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
247  * copies of the Software, and to permit persons to whom the Software is
248  * furnished to do so, subject to the following conditions:
249  *
250  * The above copyright notice and this permission notice shall be included in
251  * all copies or substantial portions of the Software.
252  *
253  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
254  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
255  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
256  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
257  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
258  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
259  * THE SOFTWARE.
260  */