Last night was no different. I was working on finishing up some final features before the release of version 0.1.0 of ease.js. It wasn’t a horribly productive day (code-wise), but it was still time that I had to squeeze in amongst other errands and the rest of my life. As usual, I committed my changes, found that I wasn’t in a state I wanted to push, suspended my PC and went off to bed. When I awoke in the morning, I found that I wasn’t able to do anything without filesystem errors. None of my drives were readable or writable.

Alright. It’s happened before. I’ll just reboot, run fsck and hope nothing important was corrupted. I wasn’t able to reboot properly (due to filesystem errors), so I just did a hard reset. To my relief, the PC booted back up just fine. I was able to reconnect to the network, restore my screen session on my server for IRC and re-open vim to begin hacking. All seemed well.

Normally, when I open vim after shutting down without giving it a chance to close, I’m spammed with messages regarding its swap files. While vim is running, it writes your changes to a swap file, one per open file, just in case something happens that causes vim to shut down without being able to save your changes. Next time you open that file, vim will notice that there’s already a swap file an will prompt the user, asking what should be done. Should vim recover from the swap file, delete it, or ignore it and edit the file anyway? Normally, I delete them all and start fresh, because everything is normally committed in Git.

But I noticed something odd. My shell, when in a Git project dir, will add additional information to the prompt (see git-ps1). Rather than saying “master” as it should of, it said “HEAD”. Sensing a problem, I didn’t delete the swap files. Instead, I typed ‘git status’ and was rather discomforted to find that every file was listed as modified and no previous commits were recognized.

Okay. That’s happened before too. Somehow, the HEAD was lost, likely due to corruption. Since most commands fail with an invalid HEAD, I just cloned my repository from GitHub and put the SHA-1 hash of its head into .git/HEAD. Worked like a charm. Unfortunately, `git reflog` was not displaying anything useful, so I couldn’t just check out one of my more recent commits. I then ran `git fsck --lost-found` to hopefully recover the commits I had made since I last pushed. It complained with a fatal error, stating that a commit was corrupt.

Suffice it to say that many commits were corrupt. After a while of trying every trick in the book for recovering lost commits (which I’m not going to go over here), I decided that it was a lost cause. Not having run `git gc` since the start of the project, there were files everywhere. There was no way I was going to manually sort through these to figure out my commit, and `git fsck` was useless because, every time I recovered or removed corrupt commits, another one was a problem. It was clear that this repository was a lost cause.

No developer likes to lose hours of work. As I said, I have to squeeze the time in when I can. Lost time is truly lost. I only have so much time in my day and, if I couldn’t recover that work, I may not be able to make the v0.1.0 release that I had hope to this weekend. Or at least get as close as possible to it. So, naturally, that was very disappointing.

Recovering the exact commits would have been ideal. The timestamps, original commit messages, etc are nice to have. With that lost, I at least wanted to try to recover the code. If I could do that, I could split it into a number of commits and hopefully get back to where I was before. So, I looked back to vim. Because I was unable to shut down the PC properly, none of the swap files were cleaned up. Therefore, I moved my old, corrupt repository to a temporary location, moved the new clone into the same dir as the original, and then chose the “recover” option for each of the files in my session and wrote them all to disk. That recovered most of my old files, which was very exciting.

Before I had shut down, I attempted to use :mksess to create a session to restore all my open files after reboot. However, since the disk was not writable, I was unable to do so. Therefore, I was stuck with an old session, which did not reload many of the files I had open. Some of those files didn’t even exist in the newly cloned repository. Fortunately, simply opening those non-existent files in vim would cause the swap file to be recognized. Vim would prompt, I would recover from the swap file, write it to disk and have my old file back.

Though I lost the commits, I now had all of my lost code back where it belongs. After recommitting everything, I didn’t have as many commits as I had previously, nor did I have the original messages, timestamps, etc, but at least I didn’t lose any actual work. Just a little bit of time, for which I was able to share an interesting experience. That has not been the only time that vim’s swap files have saved me from strangling myself. While it’s not good to rely on them for a backup solution, they are able to help in situations where you’re left with no other choice.

Had the entire disk been corrupted, I still would have been okay. My repository is on a separate physical disk than my home directory. Using the directory option in vim, you can set a different location for your swap files (it’s in the same directory as the file, by default). I set mine to ~/.vim-tmp by default. Had they been in the same directory, it’s likely that they may have been accidently lost while I was screwing around with Git trying to recover everything. If the entire disk did fail, I would have still had my work in the swap files, so I would have lost only the commits, not the code.

Moral of the story – store your swap files wisely. They’re an annoying pest when you don’t need them, but highly valuable in the off chance that they are needed.

http://stackoverflow.com/questions/3679233/are-there-still-ecmascript-3-implementation-differences-in-major-browsers/3679293#3679293

To clarify, this is the problem:

1
2
3
4
5
6
7

    var obj = {};
    obj.toString = function() {};
 
    for ( prop in obj )
    {
        // "prop" will never show 'toString' in IE
    }

I needed some way to work around this. The solution needed to be fairly elegant – that is, I don’t want to have to pass in an argument stating “yes, I set the toString property”. My workaround, though not pretty, was to test to see if toString was set:

1
2
3
4
5
6
7

    function hasToString( obj )
    {
        return ( obj.toString === Object.prototype.toString )
            ? false
            : true
        ;
    }

If the toString property of the object is equal to that of its prototype, then it’s safe to say that the property was not overwritten. However, there is a problem. We’re using Object.prototype for this test. We are not checking the parent. This is because IE does not have a __proto__ property like other browsers such as FF or Chromium. So we cannot test against the actual prototype.

This means that the above function will give you an incorrect result if the toString property was previously overridden.

Fortunately, in my use case, that will never be an issue. If it is an issue for you, then make sure you replace Object with whatever obj is an instance of.

Modules are brought into scope with the require function. You then have access to the exports of that module. In the example below, we’re interested in the Foo class of the foobar module.

1
2
3
4
5
6

// Load the "Foo" class from the "foobar" module
var Foo = require( './foobar' ).Foo,
    obj = new Foo();
 
// we would expect the following to be true, and we are correct
console.log( obj instanceof Foo ); // true

Obviously, obj is an instance of Foo. Pretty straightforward. If you use the module elsewhere in your code, you would expect that obj is still an instance of Foo:

1
2
3
4
5
6
7
8

// ...
 
function foo( obj )
{
    return ( obj instanceof require( 'foobar' ).Foo );
}
 
console.log( foo( obj ) ); // false

Huh? That above function, foo, is returning false! That did not make sense to me. As it turns out, the problem was with how I was including the module. Early on in the project, I included the module as above – by prepending ./ to the path. However, a more convenient method is to simply add it to the include path:

1
2

// add $CWD to the include path
require.paths.unshift( '.' );

You will notice that, in foo(), we were using a different path for the module. They may resolve to the same path ultimately, but Node seems to keep track of them differently.

1
2
3
4
5
6
7
8
9
10

require.paths.unshift( '.' );
 
var Foo1 = require( './foobar' ).Foo,
    Foo2 = require( './foobar' ).Foo,
    Foo3 = require( 'foobar' ).Foo,
    obj  = new Foo1();
 
console.log( obj instanceof Foo1 ); // true
console.log( obj instanceof Foo2 ); // true
console.log( obj instanceof Foo3 ); // false

This was tested with node v0.3.1-pre. As far as I am concerned, this is a bug. Foo1, Foo2 and Foo3 are all in fact the same object, however Node will reimport the module when it is included via a relative path in require.paths. If you use an absolute path in require.paths, this is not an issue. To demonstrate this, consider the following complete example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

/**
 * foobar.js
 */
console.log( '>>> foobar module loaded' );
 
exports.Foo = function()
{
}
 
 
/**
 * test.js
 */
require.paths.unshift( '.' );
 
var paths = [
    './foobar',
    __dirname + '/foobar',
    '././foobar',
    '../module-oddity/foobar',
    'foobar',
];
 
var funcs = [],
    objs  = [],
    i     = 0;
 
// load module and instantiate objects
paths.forEach( function( path )
{
    funcs[ i ] = require( path ).Foo;
    objs[ i ]  = new funcs[ i ];
 
    console.log( "Foo%d = %s", i, path );
    i++;
});
 
// compare objects
var foo_i = obj_i = 0;
funcs.forEach( function( foo )
{
    foo_i++;
    obj_i = 0;
 
    console.log();
 
    objs.forEach( function( obj )
    {
        console.log( "Foo%d instanceof obj%d: %s",
            foo_i,
            ++obj_i,
            ( obj instanceof foo )
        );
    });
});

$ node test.js
>>> foobar module loaded
Foo0 = ./foobar
Foo1 = ./foobar
Foo2 = ././foobar
Foo3 = ../module-oddity/foobar
>>> foobar module loaded
Foo4 = foobar

Foo1 instanceof obj1: true
Foo1 instanceof obj2: true
Foo1 instanceof obj3: true
Foo1 instanceof obj4: true
Foo1 instanceof obj5: false

Foo2 instanceof obj1: true
Foo2 instanceof obj2: true
Foo2 instanceof obj3: true
Foo2 instanceof obj4: true
Foo2 instanceof obj5: false

Foo3 instanceof obj1: true
Foo3 instanceof obj2: true
Foo3 instanceof obj3: true
Foo3 instanceof obj4: true
Foo3 instanceof obj5: false

Foo4 instanceof obj1: true
Foo4 instanceof obj2: true
Foo4 instanceof obj3: true
Foo4 instanceof obj4: true
Foo4 instanceof obj5: false

Foo5 instanceof obj1: false
Foo5 instanceof obj2: false
Foo5 instanceof obj3: false
Foo5 instanceof obj4: false
Foo5 instanceof obj5: true

According to the above test, you’ll notice that every relative path is considered to be an instance of the same Function. However, the single Function loaded from a URL that must be resolved though require.paths is considered to be a different Function. Also notice that the module is re-imported. Be sure to keep your naming conventions consistent.

So, there are two solutions to this issue:

• Use absolute paths. You can avoid this issue by using require( __dirname + '/path' ) rather than require( './path' ).
• Access modules consistently. If you use ./path, always use that path when accessing the module.

Hopefully in future versions of Node, this will not be an issue (I’m looking forwarding to putting a strikethru throughout this entire post). Until then, hopefully this saves you a confusing game of cat and mouse.

A patch for this problem is available on github.

First, let’s generate an array to work with. We’re going for quantity here, not size of data. Therefore, we’ll simply generate an array containing a list of integers. PHP offers a quick and easy way to do this using the array_fill() function:

1
2

// generate an array containing 100,000 elements, each with the value of 1
$data = array_fill( 0, 100000, 1 );

We want to use the array_fill() function rather than range() here because we will be summing up the values in the examples below. Range will generate incremental values, leading to integer overflows and inconsistent results across various architectures.

Note: This article assumes that the reader is running at least PHP 5.0.0. If you are running anything else, you should understand that official support for PHP 4 ended back in 2008 and you should consider upgrading immediately.

for loop

Those coming from a procedural background may be most familiar with the for loop as a means of iterating through an array. Since it is so common, let’s take a look at that first:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

$time_start = microtime( true );
$total      = 0;
 
// loop through each of the array items and sum them up
for ( $i = 0; $i < count( $data ); $i++ )
{
    $total += $data[ $i ];
}
 
// calculate total running time and output the result
$time_end = ( microtime( true ) - $time_start );
printf( "Total: %d\nloop time: %fs\n",
    $total, $time_end
);

Let’s run that test and see what type of results we get:

Total: 100000
for loop time: 0.127712s

Ouch. The time that is returned from the above test will depend on the speed of your system. I do know that, on my system, that’s a lot of time to spend simply adding up elements of an array. Let’s see how we may be able to improve that a bit.

The first thing that may jump out is the use of the count method in the condition of the for clause:

for ( $i = 0; $i < count( $data ); $i++ )

It may help to understand exactly how PHP executes the above statement. The assignment portion of the loop is executed once before any iterations begin. The step/count, which is the $i++ part, is executed after each iteration. The test expression (middle) is executed before each iteration to determine if the step should be executed and if we should continue with the loop.

Alright, that’s pretty straightforward. But that is the issue. That count function is being executed for every iteration. PHP is not caching the result of that function. That gets pretty expensive considering that it would be calling the function no less than 100,000 times.

Let’s see what happens when we change it up a bit:

1
2
3
4
5
6
7
8
9

// ...
 
// loop through each of the array items and sum them up
for ( $i = 0, $count = count( $data ); $i < $count; $i++ )
{
    $total += $data[ $i ];
}
 
// ...

Total: 100000
for loop time: 0.046609s

Wow – that is a huge improvement! We nearly tripled the speed of the iteration simply by having the conditional check a precalculated value, rather than calling the function with each iteration. That’s pretty good, right?

No; it’s still pretty slow. We can do much better.

while loop and current()

Some people may prefer to use a while loop in order to loop through the elements of an array. One of the most common ways of doing that is to use the current() function in conjunction with next():

1
2
3
4
5
6

// loop through each of the array items and sum them up
while ( $val = current( $data ) )
{
    $total += $val;
    next( $data );
}

So how does that fair speed wise. It certainly looks a little less complicated than the for loop…that means it’s faster, right?

Total: 100000
for loop time: 0.175094s

Yikes. We took a step in the wrong direction. Let’s pretend we didn’t see this.

foreach loop

PHP 4 introduced the foreach construct which provides a much more simple means of iterating through an array. Surely if it was designed for arrays, it should be faster than for:

1
2
3
4
5

// loop through each of the array items and sum them up
foreach ( $data as $val )
{
    $total += $val;
}

Notice that, in the above snippet, we are also avoiding the use of a temporary variable $i to store the current index. While PHP is undoubtedly doing so internally, we’re talking about a difference between compiled and optimized C code versus interpreted, sluggish PHP code. So that alone will provide us with a bit of a benefit, however slight.

Let’s see the result:

Total: 100000
for loop time: 0.037076s

Not too bad…we managed to shave off nearly 1/4th the time of the for loop. But I’m not satisfied.

The Problem

What do all of the above have in common? They’re looping structures. Great, so what’s the issue? If you’re coming from a compiled, high-performance language like C, there is no issue. Let’s see how long it’d take to iterate through an array containing 100,000 elements in C:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

#include <stdio.h>
#include <sys/time.h>
 
#define DATALEN 100000
 
int main()
{
    int            data[ DATALEN ];
    register long  i;  
    unsigned long  total = 0;
    struct timeval time_start, time_end;
    long           elapsed, uelapsed; 
    double         elapsed_total;
 
    // create our data array
    for ( i = 0; i < DATALEN; data[ i++ ] = 1 );
 
    // get current time
    gettimeofday( &time_start, NULL );  
 
    // loop through the array summing up the values
    for ( i = 0; i < DATALEN; i++ )
    {   
        total += data[ i ];
    }   
 
    // get total running time
    gettimeofday( &time_end, NULL );
    elapsed       = ( time_end.tv_sec - time_start.tv_sec );
    uelapsed      = ( time_end.tv_usec - time_start.tv_usec );
    elapsed_total = ( elapsed + ( (double)( uelapsed ) / 1000000 ) );
 
    // output total and loop time
    printf( "Total: %ld\nloop time: %fs\n",
        total, elapsed_total
    );  
}

Total: 100000
loop time: 0.000273s

Well, then. The point here is – PHP is a slow language, especially for looping. Wherever possible, you want to avoid it.

But you need to iterate through your arrays somehow! Does that mean you are stuck with PHP’s slow loops?

Use Built-In Functions

Fortunately, there’s certain functions available to you that can drastically improve the speed of array processing. In fact, PHP has a whole slew of functions devoted to processing and altering arrays.

Programmers coming form other languages such as C may prefer to write their own loops for processing data, because it is faster than a function call. This is not true at all with PHP; in fact, much of PHP’s power comes from it’s built-in functions. PHP itself and its libraries are written in C. Therefore, if you can use a built-in PHP function that will do the looping for you, that loop will be executed much more quickly.

Let’s take another look at our above example – summing up 100,000 values of an array. Is there a PHP function that could do this for us? array_sum() perhaps?

1
2
3
4
5
6
7
8
9
10

$time_start = microtime( true );
 
// sum up the values in the array
$total = array_sum( $data );
 
// calculate total running time and output the result
$time_end = ( microtime( true ) - $time_start );
printf( "Total: %d\nfor loop time: %fs\n",
    $total, $time_end
);

Above, we are making a single function call to array_sum() rather than going in a loop and manually adding everything up. Let’s see how this method does:

Total: 100000
for loop time: 0.012571s

Not bad. Using everything discussed here, we’ve cut our time down from the original 0.127712s to a mere 0.012571s. It’s still no C code, but our loop is 10 times faster than it was originally. It’s still written in PHP; we’re just using the tools we were given.

But wait – I said that PHP’s libraries were written in C. Why isn’t array_sum() just as fast as the C example provided above? Unfortunately, we’re still dealing with PHP’s variables and other internal representations here. It’s not just jumping to a position in memory like it does with an array in C. The array_sum() function still has to scan the PHP array to retrieve all the values. There’s no getting away from that.

Expense of Function Calls

One must also be mindful of what their loop is doing. Take a look at the following example. It calls a function in order to count all the values in an array that contain the number 2.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

<?php
 
function check_value( $val )
{
    return ( $val === 2 )
        ? 1
        : 0
    ;
}
 
// generate an array with 1/3 values containing 1, the rest containing 2
$data = (
    array_fill( 0, 10000, 1 )
    + array_fill( 10000, 20000, 2 )
);
 
$time_start = microtime( true );
 
// count the values in the array greater than 50000
$count = 0;
foreach ( $data as $val )
{
    $count += check_value( $val );
}
 
// calculate total running time and output the result
$time_end = ( microtime( true ) - $time_start );
printf( "Count: %d\nfor loop time: %fs\n",
    $count, $time_end
);

Count: 20000
for loop time: 0.043597s

Above, we called the check_value() function 30,000 times. Functions do an excellent job at improving code clarity and reducing duplicate code. However, function and method calls are expensive. Consider what happens when we get rid of the function and do all the processing in the body of the loop:

1
2
3
4
5
6
7
8
9

// count the values in the array greater than 50000
$count = 0;
foreach ( $data as $val )
{
    if ( $val === 2 )
    {
        $count++;
    }
}

If we run it again using that loop instead of the previous one, we get the following result:

Count: 20000
for loop time: 0.013397s

That’s a significant speed improvement. Now, I’m not advocating that you get rid of all of your functions (though I would advocate preprocessor macros in PHP). However, consider the performance implications of excessive function or method calls where it is important. In most situations, the benefits you gain from legibility will outweigh the performance pitfalls.

It should also be noted that under many circumstances, the overhead of the function call may be insignificant. If your method takes 0.3 seconds to execute, you’re not going to care about milliseconds of overhead.

Memory Tradeoff & Apparent Processing

Let’s continue with the example from the previous section (counting the number of elements in an array that contain the value 2). PHP does not contain a function that can explicitly search an array for the given value and return the number of results. It does, however, have something very similar – array_count_values().

The array_count_values() function will loop through the array and maintain a count of each of the values. It will then return an array containing the results. Therefore, in our above example, it would return an array much like the following:

1
2
3
4

array(
    1 => 10000,  // there are 10,000 1s in our data array
    2 => 20000,  // there are 20,000 2s in our data array
);

That’s a bit more information than we want. In fact, what if we had an array containing hundreds of different values? Wouldn’t it take longer to count every element than a single one (well, no, but one might assume)? That would account for a bit more memory usage as well, even though it does give us the answer we are looking for. Which is a more elegant solution?

When attempting to optimize code, developers must often have to choose between CPU time and memory footprint. This is one of those situations due to language limitations. Let’s take a look at how much time it takes for PHP to count the values for us:

1
2
3
4
5
6

// count the values in the array greater than 50000
$count_data = array_count_values( $data );
$count      = $count_data[ 2 ];
 
// output memory consumption
printf( "Memory Consumption: %d bytes\n", memory_get_usage( true ) );

Memory Consumption: 6815744 bytes
Count: 20000
for loop time: 0.003805s

Even though we’re gathering more information, it’s still 3.5x faster than counting only a single value manually. In fact, I’m willing to bet that it even consumed less memory than our previous example, simply due to the fact that we aren’t having to deal with userland variables and function calls:

(Our example using check_value(), with memory output)

Memory Consumption: 7077888 bytes
Count: 20000
for loop time: 0.043128s

It seems that counting a single element using our check_value() method used 262144 more bytes than array_count_values()! Damn you, PHP! Yes, it’s unfortunate that considerations like this must be made, but you’d be surprised how many internal methods really do provide both strong memory and CPU benefits even though they “do more work”. Userland consumes considerable amounts of memory.

That isn’t to say that array_count_values() can’t consume more memory. Like I said previously – if it returns an array with thousands of values, it’s going to offset that memory savings.

ArrayObjects and Iterators

PHP 5 began a strong move toward Object-Oriented programming. It provides a number of powerful components that deal with iteration – specifically Traversable objects and Iterators. They provide a benefit to developers in the sense that it makes code much easier to understand and allows for powerful OO implementations, but does it provide any performance benefit?

Firstly, let’s see what happens when we loop through an ArrayObject rather than a normal array:

1
2

// generate an array containing 100,000 elements, each with the value of 1
$data = new ArrayObject( array_fill( 0, 100000, 1 ) );

Total: 100000
loop time: 0.061663s

This is compared to our foreach example with a result of 0.037076s. So we did loose a bit of time there. However, that does not mean you shouldn’t use ArrayObjects. In fact, I use them a great deal in OO scripts, because ArrayObjects coupled with Iterators provide powerful designs that aren’t quite as elegant when using procedural code. However, when performance is a requirement, I have to steer clear of them.

You will find that the Iterator object provides very little benefit over a conventional foreach loop as well. The only time I make use of an Iterator is when it contains additional logic that determines what results it should return (e.g. to iterate only over odd numbers), or if the implementation allows for an Iterator to be passed in at runtime to determine what results should be returned.

1
2
3
4
5
6
7

// loop through each of the array items and sum them up
$iterator = $data->getIterator();
while ( $iterator->valid() )
{
    $total += $iterator->current();
    $iterator->next();
}

Total: 100000
loop time: 0.291542s

In fact, that’s our slowest method yet. So, just be wise when weighing the costs and benefits. If performance doesn’t matter – go ahead. Use whatever implementation is best for you. That’s why you have the option. If performance is a factor, don’t even glance at those objects. Maybe future versions of PHP will enhance the functionality to the point where their speeds are equivalent to the loop structures.

Wall Of Text Summary

PHP provides a number of ways to iterate through arrays – rest assured that we haven’t nearly covered them all here. Out of all the loop structures available, foreach is the fastest for iteration. However, it comes up short when compared to built-in functions designed for array processing. Where possible, those built-in functions should be used, even where it may seem at first glance that it may be slower. They often provide a very strong performance benefit – both CPU and memory wise.

PHP 5 introduced a number of new means of iteration through the use of objects. Certain implementations may do well to improve code legibility, and may enable the developer to implement some fairly powerful object-oriented designs, but when performance is a factor, you want to steer clear of them.

Hopefully this article helped to clear up some questions. I expect not to see any more for loops with count() in the loop test expression!

Namespaces are new as of PHP 5.3. Therefore, there’s very few people actually writing extensions with namespace support. To make matters worse, documentation of the Zend core is very poor. Much of my time is spent reading through the code, trying to figure out what macros do what, etc. This was another one of those cases.

Normal PHP Functions:

Normal PHP functions are placed within the functions list using the PHP_FE macro. The actual function is defined using PHP_FUNCTION. So your code may look like this:

1
2
3
4
5
6
7
8
9
10

static function_entry my_functions[] = {
// ...
PHP_FE( myfunc, NULL )
// ...
};
 
PHP_FUNCTION( myfunc )
{
// Function body here
}

If you were to call myfunc() from within userland (within a PHP script), it would execute the C code defined within the body of PHP_FUNCTION( myfunc ). Simple enough. Now what if we wanted namespaces?

Using Namespaces

The short answer:
Replace PHP_FE( myfunc, NULL ) with ZEND_NS_FE( "myns", myfunc, NULL ). But if you actually want to know why, keep reading.

The detailed answer:
PHP_FE is defined within main/php.h. That points us to the ZEND_FE macro defined within Zend/zend_API.h. While looking through this file, I noticed a ZEND_NS_FE macro in there, and figured it must be referring to namespaces. So I figured that logically, there would be a PHP_NS_FE macro, right? Nope. There’s no such macro defined anywhere. At least not at this point in time. Hopefully there will be for the final release of 5.3.
yourself, however that will ruin your chances of your extension becoming portable. Other developers aren’t going to want to patch their php.h file to use it.

1
2

#define ZEND_FE(name, arg_info)						ZEND_FENTRY(name, ZEND_FN(name), arg_info, 0)
#define ZEND_NS_FE(ns, name, arg_info)					ZEND_NS_FENTRY(ns, name, ZEND_FN(name), arg_info, 0)

Looking over the macros, you see that both macros make use of the ZEND_FN macro. A quick glance at that macro shows that it converts our “myfunc” function into “zif_myfunc”:

1

#define ZEND_FN(name) zif_##name

This means that internally, zend will use the same function name regardless of whether or not it is contained within a namespace. In other words, we don’t even have to touch our PHP_FUNCTION line! Great – so then what’s different? Let’s take a look at ZEND_NS_FENTRY:

1

#define ZEND_NS_FENTRY(ns, zend_name, name, arg_info, flags)		ZEND_RAW_FENTRY(ZEND_NS_NAME(ns, #zend_name), name, arg_info, flags)

The difference here is that Zend is making use of the ZEND_NS_NAME macro:

1

#define ZEND_NS_NAME(ns, name)			ns"\\"name

Ah-ha! (Ignoring the fact that it’s, at present, at the top of the file.) While internally our function name is no different, Zend will only call it if it is prefixed with the namespace name from within userland. The above macro converts our function name to “myns\myfunc”. So, our updated code may look like this:

1
2
3
4
5
6
7
8
9
10
11
12

#define MY_NS "myns"</code>
 
static function_entry my_functions[] = {
// ...
ZEND_NS_FE( MY_NS, myfunc, NULL )
// ...
};
 
PHP_FUNCTION( myfunc )
{
// Function body here
}

We can then call our function via “myns\myfunc”. Remember – you must use ZEND_NS_FE. As of this time of writing, PHP_NS_FE does not exist! Of course, that could easily be solved by adding it to your own source files yourself, but it’s still a messy task. I’ve submitted a bug report to the PHP team detailing the additions (I couldn’t find where to submit a patch), so hopefully it’ll make it in. Until then, feel free to add this to your header file, along with any other ZEND_NS_* aliases you may need:

1
2
3

#ifndef PHP_NS_FE
#    define PHP_NS_FE ZEND_NS_FE
#endif

Summary

While diving into the C code isn’t necessary to use namespaces, it does greatly improve your understanding of how the system works. Because there is so little documentation, I encourage you to keep looking through PHP’s source and see what you find. There are goodies hidden everywhere that may be incredibly useful to you, and save you a lot of time. Look through existing extensions within the ext folder and see if any of them use methods that you are interested in.

It was the unfortunate circumstance that none of the extensions did make use of namespace support. So I was on my own to look for it. I hope this helps save some frustration for others, especially those new to Zend that are just trying to figure out whether or not porting their code to C is worth the effort.

Well, I recently installed the new PHP 6 snapshot from http://snaps.php.net/ and found that my code was broken – a pleasent surprise I’m sure to many PHP developers. Just think about the ones who don’t even know about the change. Imagine that frustration. Anyway, I quickly realized that the separator had changed. Thankfully, it’s pretty much a simple search-and-replace to modify my namespaces to use the new separator using the sed utility. Be sure to back up your data before performing any batch replacing on your scripts.

I suppose I could help out by providing a script to help you make that change. In my situation, all I have to do is replace “webkernel::” with “webkernel\”, and “cli::” with, “cli\”. Simply paste the below command into a BASH terminal within the root directory of your project, and it will recursively replace all occurances in all PHP files. Again, BACK UP YOUR WORK! I’m not to be held responsible for any irreversible damage done to your code. Be sure you understand the command before running it.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

#!/bin/bash
if [ $# -lt 2 ]; then
    echo Usage: rsed "FILEPATTERN" "REGEXP"
    exit 1
fi
 
for i in `find . -name "$1"`; do
    # Make a backup
    mv $i "$i.bak"
 
    # Perform the replacement
    sed "$2" "$i.bak" > $i
    echo $i
 
    # Remove the backup - comment out to keep backup
     rm "$i.bak"
done
 
echo Done.

Save the above as rsed, chmod +x, and run it using the following as an example: ./rsed "*.php" "s/webkernel::/webkernel\\\\g/" (in the previous command, “\\\\” = “\”). Ensure you use an extension like “*.php” for the file pattern – don’t just use “*” or it’ll cause problems, as it’ll match directories as well. If you have files that contain no extension, replace them manually.

Alternatively, in the above script, you may instead decide to use grep -rl "webkernel::" ./ to modify any file that contains the phrase you’re trying to replace, rather than search for only PHP files (this was more flexible in my case).

NOTE: Be sure to check for strings containing the replaced expression in your code. The replacement may end up escaping part of the string, causing errors (e.g. ‘webkernel::’ to ‘webkernel\’). Good luck!

I speak of creating a stream wrapper (I’m creating the datapack wrapper for the MyCustomBB project). When you call ftell() on the handle to the stream, the PHP core calls the stream_tell() function within the class defined for that wrapper (in this case, datapack::stream_tell). However, PHP only seems to call this function after you use fseek() on your stream. Until then, it caches the file pointer position itself. Okay, seems reasonable. However, unless your stream_seek() function returns a value of TRUE (or any non-false value), PHP ignores the fact that the function was called, and continues to cache it itself.

Okay, so what’s the problem? If you check the PHP documentation for the fseek() function, you will see the following quote for the return value:

Upon success, returns 0; otherwise, returns -1. Note that seeking past EOF is not considered an error.

Okay; to be complaint with this standard, my stream_seek() function returned a value of zero upon success, and -1 upon failure. Rather, it simply returned the value that was returned by fseek() (return fseek( $this->handle, $seek_pos);). However, 0 = FALSE. Therefore, PHP ignored it and would not call stream_tell() until I had stream_seek() return a value of TRUE upon success:

return ( fseek( $this->handle, $seek_pos ) == -1 ) ? FALSE : TRUE;

Then, it worked. You can imagine my irritation. However, in the PHP documentation, which I did overlook, it states that stream_seek() should indeed return TRUE on success. My bad, but very stupid of the PHP developers to do.

And just to think; I almost had to return the position via fseek() and use fseek( $handle, 0, SEEK_CUR ) in place of ftell().