Home » Networking » Net_Server » Manual

Introduction

Introduction – Introduction to Net_Server

Introduction to Net_Server

Net_Server provides an interface to create daemon application based on the sockets extension of PHP 4. In order to use Net_Server you need a PHP version greater or equal PHP 4.2, it is meant to be used with PHP-CLI.

Net_Server uses a driver based architecture that allows you to switch the drivers for your daemons. Currently a forking and a non-forking driver are available, others will follow.

As Net_Server provides an abstraction layer for the sockets extension, you do not need internal knowledge about the PHP functions. All you have to do is implement callback functions for events in your daemon, like handling new connections or incoming data.

Example

Example – using Net_Server

Creating a simple daemon

The following example shows, how easy it is to build a forking server that receives data and sends it back to the user.

Creating a simple talkback daemon

#!/usr/local/bin/php
<?php
    // server base class
    require_once 'Net/Server.php';
    
    // base class for the handler
    require_once 'Net/Server/Handler.php';

/**
 * simple example that implements a talkback.
 *
 * Normally this should be a bit more code and in a separate file
 */
class Net_Server_Handler_Talkback extends Net_Server_Handler
{
   /**
    * If the user sends data, send it back to him
    *
    * @access   public
    * @param    integer $clientId
    * @param    string  $data
    */
    function    onReceiveData( $clientId = 0, $data = "" )
    {
        $this->_server->sendData( $clientId, "You said: $data" );
    }
}
    
    // create a server that forks new processes
    $server  = &Net_Server::create('fork', 'localhost', 9090);
    
    $handler = &new Net_Server_Handler_Talkback;
    
    // hand over the object that handles server events
    $server->setCallbackObject($handler);
    
    // start the server
    $server->start();
?>

Class Summary Net_Server

Class Summary Net_Server – PHP socket server base class

PHP socket server base class

This class must only be used to create a new server using the static method 'create()'.

To handle the events that happen while the server is running you have to create a new class that handles all events.

1     require_once 'myHandler.php';
2      require_once 'Net/Server.php';
3
4      $server = &

::

('fork', 'localhost', 9090);
5
6      $handler = &new myHandler;
7
8      $server->setCallbackObject($handler);
9
10     $server->start();

See Server/Handler.php for a baseclass that you can use to implement new handlers.

Class Trees for Net_Server

• Net_Server

Net_Server::create

Net_Server::create() – create a new server

Synopsis

void& Net_Server::create ( string $type , string $host , integer $port )

Description

Currently two types of servers are supported:

• 'sequential', creates a server where one process handles all request from all clients sequentially
• 'fork', creates a server where a new process is forked for each client that connects to the server. This only works on *NIX

Parameter

string $type

type of the server

string $host

hostname

integer $port

port

Throws

throws no exceptions thrown

static

static

Note

This function can not be called statically.

Class Summary Net_Server_Driver

Class Summary Net_Server_Driver – Base class for all drivers

Base class for all drivers

This package is not documented yet.

Class Trees for Net_Server_Driver

• PEAR
  • Net_Server_Driver

Net_Server_Driver::getLastSocketError

Net_Server_Driver::getLastSocketError() – return string for last socket error

Synopsis

string Net_Server_Driver::getLastSocketError ( mixed &$fd )

Description

This package is not documented yet.

Parameter

mixed &$fd

Return value

returns last error

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver::setCallbackObject

Net_Server_Driver::setCallbackObject() – register a callback object, that is used to handle all events

Synopsis

void Net_Server_Driver::setCallbackObject ( object &$object )

Description

This package is not documented yet.

Parameter

object &$object

callback object

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver::setDebugMode

Net_Server_Driver::setDebugMode() – set debug mode

Synopsis

void Net_Server_Driver::setDebugMode ( mixed $debug , string $dest = "stdout" )

Description

This package is not documented yet.

Parameter

mixed $debug

[text|htmlFALSE]

string $dest

destination of debug message (stdout to output or filename if log should be written)

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Class Summary Net_Server_Driver_Fork

Class Summary Net_Server_Driver_Fork – Forking server class.

Forking server class.

This class will fork a new process for each connection. This allows you to build servers, where communication between the clients is no issue.

Events that can be handled:

• onStart
• onConnect
• onClose
• onReceiveData

Class Trees for Net_Server_Driver_Fork

• PEAR
  • Net_Server_Driver
    • Net_Server_Driver_Fork

Net_Server_Driver_Fork Inherited Methods

Net_Server_Driver_Fork::broadcastData

Net_Server_Driver_Fork::broadcastData() – send data to all clients

Synopsis

void Net_Server_Driver_Fork::broadcastData ( string $data , array $exclude = array() )

Description

This package is not documented yet.

Parameter

string $data

data to send

array $exclude

client ids to exclude

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver_Fork::closeConnection

Net_Server_Driver_Fork::closeConnection() – close the current connection

Synopsis

void Net_Server_Driver_Fork::closeConnection ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver_Fork::getClientInfo

Net_Server_Driver_Fork::getClientInfo() – get current information about a client

Synopsis

array Net_Server_Driver_Fork::getClientInfo ( )

Description

This package is not documented yet.

Return value

returns information about the client

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver_Fork::getClients

Net_Server_Driver_Fork::getClients() – get current amount of clients

Synopsis

PEAR_Error Net_Server_Driver_Fork::getClients ( )

Description

not possible with forking

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver_Fork::isConnected

Net_Server_Driver_Fork::isConnected() – check, whether a client is still connected

Synopsis

boolean Net_Server_Driver_Fork::isConnected ( integer $id )

Description

This package is not documented yet.

Parameter

integer $id

client id

Return value

returns true if client is connected, false otherwise

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver_Fork::sendData

Net_Server_Driver_Fork::sendData() – send data to a client

Synopsis

void Net_Server_Driver_Fork::sendData ( string $data , boolean $debugData = true )

Description

This package is not documented yet.

Parameter

string $data

data to send

boolean $debugData

flag to indicate whether data that is written to socket should also be sent as debug message

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver_Fork::serviceRequest

Net_Server_Driver_Fork::serviceRequest() – service the current request

Synopsis

void Net_Server_Driver_Fork::serviceRequest ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver_Fork::setMaxClients

Net_Server_Driver_Fork::setMaxClients() – set maximum amount of simultaneous connections

Synopsis

void Net_Server_Driver_Fork::setMaxClients ( int $maxClients )

Description

this is not possible as each client gets its own process

Parameter

integer $maxClients

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver_Fork::shutDown

Net_Server_Driver_Fork::shutDown() – shutdown server

Synopsis

void Net_Server_Driver_Fork::shutDown ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver_Fork::start

Net_Server_Driver_Fork::start() – start the server

Synopsis

void Net_Server_Driver_Fork::start ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Class Summary Net_Server_Driver_Sequential

Class Summary Net_Server_Driver_Sequential – Sequential server class.

Sequential server class.

This class will handles all connections in one server process. This allows you to build servers, where communication between the clients is easy. The drawback is that clients are served sequentially (hence the name). If you send large blocks of data to a client, the others will have to wait. For servers where communication between clients is not needed, use Net_Server_Fork instead.

Events that can be handled:

• onStart
• onConnect
• onConnectionRefused
• onClose
• onIdle
• onReceiveData
• onShutdown

Class Trees for Net_Server_Driver_Sequential

• PEAR
  • Net_Server_Driver
    • Net_Server_Driver_Sequential

Net_Server_Driver_Sequential Inherited Methods

Net_Server_Driver_Sequential::acceptConnection

Net_Server_Driver_Sequential::acceptConnection() – accept a new connection

Synopsis

int Net_Server_Driver_Sequential::acceptConnection ( resource &$socket )

Description

This package is not documented yet.

Parameter

resource &$socket

socket that received the new connection

Return value

returns internal ID of the client

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver_Sequential::broadcastData

Net_Server_Driver_Sequential::broadcastData() – send data to all clients

Synopsis

void Net_Server_Driver_Sequential::broadcastData ( string $data , array $exclude = array() )

Description

This package is not documented yet.

Parameter

string $data

data to send

array $exclude

client ids to exclude

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver_Sequential::closeConnection

Net_Server_Driver_Sequential::closeConnection() – close connection to a client

Synopsis

void Net_Server_Driver_Sequential::closeConnection ( mixed $id = 0 , int $clientID )

Description

This package is not documented yet.

Parameter

mixed $id

integer $clientID

internal ID of the client

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver_Sequential::getClientInfo

Net_Server_Driver_Sequential::getClientInfo() – get current information about a client

Synopsis

array Net_Server_Driver_Sequential::getClientInfo ( int $clientId )

Description

This package is not documented yet.

Parameter

integer $clientId

ID of the client

Return value

returns information about the client

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver_Sequential::getClients

Net_Server_Driver_Sequential::getClients() – get current amount of clients

Synopsis

int Net_Server_Driver_Sequential::getClients ( )

Description

This package is not documented yet.

Return value

returns amount of clients

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver_Sequential::isConnected

Net_Server_Driver_Sequential::isConnected() – check, whether a client is still connected

Synopsis

boolean Net_Server_Driver_Sequential::isConnected ( integer $id )

Description

This package is not documented yet.

Parameter

integer $id

client id

Return value

returns true if client is connected, false otherwise

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver_Sequential::sendData

Net_Server_Driver_Sequential::sendData() – send data to a client

Synopsis

void Net_Server_Driver_Sequential::sendData ( int $clientId , string $data , boolean $debugData = true )

Description

This package is not documented yet.

Parameter

integer $clientId

ID of the client

string $data

data to send

boolean $debugData

flag to indicate whether data that is written to socket should also be sent as debug message

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver_Sequential::setMaxClients

Net_Server_Driver_Sequential::setMaxClients() – set maximum amount of simultaneous connections

Synopsis

void Net_Server_Driver_Sequential::setMaxClients ( int $maxClients )

Description

This package is not documented yet.

Parameter

integer $maxClients

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver_Sequential::shutDown

Net_Server_Driver_Sequential::shutDown() – shutdown server

Synopsis

void Net_Server_Driver_Sequential::shutDown ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver_Sequential::start

Net_Server_Driver_Sequential::start() – start the server

Synopsis

void Net_Server_Driver_Sequential::start ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Class Summary Net_Server_Handler

Class Summary Net_Server_Handler – Base class for all handlers

Base class for all handlers

This package is not documented yet.

Class Trees for Net_Server_Handler

• Net_Server_Handler

Net_Server_Handler::onClose

Net_Server_Handler::onClose() – onClose handler

Synopsis

void Net_Server_Handler::onClose ( integer $clientId = 0 )

Description

This handler is called, when a client disconnects from the server Available in:

• Net_Server_Sequential
• Net_Server_Fork

Parameter

integer $clientId

unique id of the client, in Net_Server_Fork, this is always 0

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Handler::onConnect

Net_Server_Handler::onConnect() – onConnect handler

Synopsis

void Net_Server_Handler::onConnect ( integer $clientId = 0 )

Description

This handler is called, when a new client connects Available in:

• Net_Server_Sequential
• Net_Server_Fork

Parameter

integer $clientId

unique id of the client, in Net_Server_Fork, this is always 0

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Handler::onConnectionRefused

Net_Server_Handler::onConnectionRefused() – onConnectionRefused handler

Synopsis

void Net_Server_Handler::onConnectionRefused ( integer $clientId = 0 )

Description

This handler is called, when a new client tries to connect but is not allowed to Available in:

• Net_Server_Sequential

Parameter

integer $clientId

unique id of the client

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Handler::onIdle

Net_Server_Handler::onIdle() – onIdle handler

Synopsis

void Net_Server_Handler::onIdle ( )

Description

This handler is called whenever the server is idle (has nothing to do), and that for a given number of seconds (timeout). Currently, only the sequential driver supports this handler.

The timeout can be specified by passing the desired number of seconds to setIdleTimeout(). By default, the timeout is set to NULL, which means that the handler is deactivated.

Note

This function can not be called statically.

Net_Server_Handler::onReceiveData

Net_Server_Handler::onReceiveData() – onReceiveData handler

Synopsis

void Net_Server_Handler::onReceiveData ( integer $clientId = 0 , string $data = "" )

Description

This handler is called, when a client sends data to the server Available in:

• Net_Server_Sequential
• Net_Server_Fork

Parameter

integer $clientId

unique id of the client, in Net_Server_Fork, this is always 0

string $data

data that the client sent

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Handler::onShutdown

Net_Server_Handler::onShutdown() – onShutdown handler

Synopsis

void Net_Server_Handler::onShutdown ( )

Description

This handler is called, when the server is stopped. Available in:

• Net_Server_Sequential

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Handler::onStart

Net_Server_Handler::onStart() – onStart handler

Synopsis

void Net_Server_Handler::onStart ( )

Description

This handler is called, when the server starts. Available in:

• Net_Server_Sequential
• Net_Server_Fork

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Handler::setServerReference

Net_Server_Handler::setServerReference() – set a reference to the server object

Synopsis

void Net_Server_Handler::setServerReference ( object Net_Server_* &$server )

Description

This is done automatically when the handler is passed over to the server

Parameter

object Net_Server_*; &$server

object

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Package Net_Server Constants

Package Net_Server Constants – Constants defined in and used by Net_Server

All Constants

Constants defined in Server.php