Getting started

Getting started

Introduction

PHP has built in support for various types of network streams, such as HTTP and sockets. One problem that arises with them is the fact that a single fread/fwrite call might not read/write all the data you intended... regardless of whether you're in blocking mode or not. While the PHP manual offers a workaround in the form of a loop with a few variables, using it every single time you want to read/write can be tedious.

This package abstracts this away, so that when you want to get exactly N amount of bytes, you can be sure the upper levels of your app will be dealing with N bytes. Oh, and the functionality is nicely wrapped in an object (but that's just the icing on the cake).

Requirements

• PHP 5.3.0 or later
• Enabled outgoing connections with stream_socket_client() when using TcpClient.
• Enabled incoming connections with stream_socket_accept() when using TcpServerConnection.
• [optional] The OpenSSL extension (bundled with PHP by default; needs to be enabled in php.ini or during compilation; required only if you want to use encrypted connections)
• [optional] PEAR2_Cache_SHM (bundled with the archive; needed only if you use persistent connections)

Notes

• Many shared web hosts choose to disable stream_socket_client(), and it's close relative fsockopen() as well. When they don't disable them, they often render them next to useless by forbidding outgoing connections with the server's firewall. Often, popular ports, such as 21, 80, 443, and similar are allowed, so if you're making an application that normally requires connecting to a different port, you may try to switch to one of these ports instead. If even that doesn't work, you need to contact your host. If you're on your own server, and fail to connect, configure your server's firewall so that it enables PHP to make outgoing connections (at least to the ip:port combo to which you want to connect). Depending on how you run PHP as:

PHP running as (SAPI)	Executable folder	Executable file to whitelist
		UNIX	Windows
Apache module	Apache's "bin" folder	httpd	httpd.exe
(F)CGI	PHP's folder	php-cgi	php-cgi.exe
CLI	PHP's folder	php	php.exe

• Same problem as above exists with stream_socket_server(), and by extension, stream_socket_accept(). In your firewall, allow for the appropriate executable to accept incoming connections to allow proper work of TcpServerConnection.

Installation

Direct PHAR usage

If you download the ".phar" archive, you can just include the archive, and be ready to go, like for example:

<?php
//You may want to include a namespace declaration here
require_once 'PEAR2_Net_Transmitter-1.0.0b2.phar';
//Use any PEAR2_Net_Transmitter class from here on

Installation with Pyrus/PEAR2 (recommended)

Assuming you have installed Pyrus, you can install PEAR2_Net_Transmitter from the pear2.php.net channel with

php pyrus.phar install PEAR2_Net_Transmitter-beta

If you've decided to not use the pear2.php.net channel, but instead install directly from the archive distributed at the project page, you can use

php pyrus.phar install /path/to/downloaded/archive.tgz

Installation with PEAR

Like most PEAR2 packages, PEAR2_Net_Transmitter is compatible with the PEAR installer. However, you have to first discover the PEAR2 channel with

pear channel-discover pear2.php.net

and only then install PEAR2_Net_Transmitter with

pear install pear2/PEAR2_Net_Transmitter-beta

Installation with Composer

This package is available from packagist.org, so all you have to do is to go to your project's directory (where your composer.json is), and run

composer require pear2/net_transmitter:*@beta

Due to the way composer works, you need to add each optional dependency manually. So for example, if you want to use persistent connections, you'd also need to execute

composer require pear2/cache_shm:*@alpha

Manual installation

This package has no external dependencies, so you can just download an archive, and extract the contents of the "src" folder wherever you like. To emulate the PEAR2 installer, you can place the files in a folder that's within your include_path.

Installation from the repository (with Git)

If you want to get the "cutting edge", unpackaged version of PEAR2_Net_Transmitter, you'll need to have Git. Once you have it, create a folder to place the package and its dependencies in, navigate to it from the command line, and execute the following commands:

git clone https://github.com/pear2/Net_Transmitter.git Net_Transmitter.git
git clone https://github.com/pear2/Cache_SHM.git Cache_SHM.git

Note: If you plan to contribute to this project, please use GitHub's "fork" feature instead, and then apply "git clone" on it, instead of the original repository.

Troubleshooting

If the package doesn't work, you can download the "phar" file (maybe rename it from ".phar" to ".php"), and run it in your browser or command line.

When you do that, you should see the version of the package, along with some messages indicating if you're missing any of the requirements. If all requirements are present, you'll see suggestions as to what may go wrong when connecting to a host, and suggestions on how to fix it.