Hexdump

KO | EN

gitlite — search

#hacktoberfest #react #ai #go #golang #android #machine-learning #rust #linux #docker #cli #vue #security #mcp

(★ 14)

Hexdump functionality for php

Hexdump Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Hexdump

This library provides a hexdump() function for php. I've developed it once when I was required to create a PHP client for a binary network protocol and used it to debug the traffic.

What you can see now is the result from grabbing the code from my old harddisk, refactoring it, adding several features, creating a PEAR installer and finally exporting it to github.

Enjoy!

#Table of Contents

- [Hexdump](#hexdump)
	- [Installation](#installation)
		- [Using the PEAR installer](#using-the-pear-installer)
		- [Manually download and install files](#manually-download-and-install-files)
	- [Documentation](#documentation)
		- [hello world](#hello-world)
		- [The Hexdump class behind the scenes](#the-hexdump-class-behind-the-scenes)
		- [Available Options](#available-options)
	- [Code Examples](#code-examples)
		- [hello world (8 columns)](#hello-world-8-columns)
		- [Uppercased Hex chars](#uppercased-hex-chars)
		- [Dump this document](#dump-this-document)
		- [Dumping to stderr](#dumping-to-stderr)
		- [Formatting as HTML](#formatting-as-html)
	- [Using phphd from the command line](#using-phphd-from-the-command-line)
		- [Example usage](#example-usage)

## Installation

To install Hexdump you can use the PEAR installer or get a tarball and install the files manually.

___
### Using the PEAR installer

If you haven't discovered my pear channel yet you'll have to do it. Also you should issue a channel update:

pear channel-discover metashock.de/pear
    pear channel-update metashock

After this you can install Hexdump. The following command will install the lastest stable version:

pear install -a metashock/Hexdump

If you want to install a specific version or a beta version you'll have to specify this version on the command line. For example:

pear install -a metashock/Hexdump-0.2.0

___
### Manually download and install files

Alternatively, you can just download the package from http://www.metashock.de/pear and put into a folder listed in your `include_path`. Please refer to the php.net [documentation](http://php.net/manual/en/ini.core.php#ini.include-path) of the `include_path` directive.

## Documentation

Before using the `hexdump()` function you'll have to include Hexdump.php. If you followed the installation instructions you don't need to worry about where the file is located in your classpath. Type:

```php
require_once 'Hexdump.php';
```

If `require_once` fails, something went wrong with the installation.

___
### hello world

A simple hello world should be most intuitive. Just call the function `hexdump()` with the data as argument:

```php
hexdump("hello world!\n");
```

Output:

00000000: 68 65 6c 6c 6f 20 77 6f 72 6c 64 21 0a          |hello.world!.|

___
### The signature

The hexhump function has the following signature:

```php
string hexdump($data, $ncols = 16, $format = 'plain', $uppercase = TRUE, $output = 'stdout');
```

Please refer to [available options](#Available-Options) section of this document to get information about the params itself and possible values for them.

___
### The `Hexdump` class behind the scenes

Although you will in most cases just use the function `hexdump()`, the work behind the scenes is done by the `Hexdump` class. `hexdump()` is just a wrapper for `Hexdump::draw()`

```php
$hexdump = new Hexdump();
$hexdump->draw("hello world!\n");
```
This code will behave exactly the same as the hello world example above.

So why an extra class? The purpose of the Hexdump class is to act as a global configuration container for `hexdump()` in order to keep the syntax of the function itself succinct.

Global options can be set or queried by using the static method `Hexdump::option()`

```php
// set option value
Hexdump::option('option_name', $option_value);
// get option value
$option_value = Hexdump::option('option_name');
```

If you have non default options, you should set this options globally with `Hexdump::option()`. Doing it you will save to pass them in every call to hexdump().

___
### Available Options

The following options are available. Default values are printed bold.

<table>
  <tr>
    <th>Option</th>
    <th>Type</th>
    <th>Possible Values</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>ncols</td>
    <td>unsinged integer</td>
    <td>The value must be greater than zero. Defaults to <b>16</b></td>
    <td>The number of bytes printed per line</td>
  </tr>
  <tr>
    <td>format</td>
    <td>string</td>
    <td><ul><li><b>plain</b></li><li>html</li></ul></td>
    <td>When set to true hexdump() will return the hexdump as a string instead of directly output it to stdout</td>
  </tr>
  <tr>
    <td>uppercase</td>
    <td>boolean</th>
    <td><ul><li>true</li><li><b>false</b></li></ul></td>
    <td>Uppercasing hex numbers? (FF instead of ff)</td>
  </tr>
  <tr>
    <td>output</td>
    <td>string</th>
    <td><ul><li><b>stdout</b></li><li>stderr</li><li>none</li></ul></td>
    <td>When set to true hexdump() will return the result as a string instead of directly printing to stdout</td>
  </tr>
</table>

## Code Examples

Note that all example assume that you have included Hexdump.php

```php
<?php

require_once 'Hexdump.php';
```

### hello world (8 columns)

```php
hexdump("hello world!\n", 8);
```

Output:

00000000: 68 65 6c 6c 6f 20 77 6f |hello.wo|
    00000008: 72 6c 64 21 0a          |rld!.|

___
### Uppercased Hex chars

```php
hexdump("hello world!\n", 8, PHP_EOL, TRUE);
```

Output:
  
    00000000: 68 65 6C 6C 6F 20 77 6F |hello.wo|
    00000008: 72 6C 64 21 0A          |rld!.|

___
### Dump this document

```php
hexdump(file_get_contents('README.md'));
```

Output:

```php
// set the option globally
Hexdump::option('output', 'stderr');

// all pending hexdumps will go to stderr
hexdump($data);
hexdump($moreData);
// ...
```

---
### Formatting as HTML

```php

// to get a HTML dump do either 
hexdump("<hello world!>\n", 16, 'html');

// ... or set the option globally
Hexdump::option('format', 'html');

// now all pending hexdumps will be formatted as HTML
hexdump($data);
// ...
```

Output:

<pre>00000000: 3c 68 65 6c 6c 6f 20 77 6f 72 6c 64 21 3e 0a    |&lt;hello.world!&gt;.|
    </pre>

As you can see html special chars will be replaced by entities and the dump is wrapped in `<pre>` tags. This will display the hexdump correctly layouted on a HTML page.

## Using `phphd` from the command line

In addition to Hexdump.php the package contains a command line executable `phphd`. It prints hexdumps either from files or from stdin. Although linux distributions usually provide a hexdump utility it might be helpful in some cases. Especially when you are working on Windows.

`phphd` comes with the following options:

Usage : ./phphd [OPTIONS] [FILE]

Prints a hexdump of FILE to stdout. If FILE was omitted ./phphd reads from stdin.

-c COLUMNS     Number of bytes per row. COLUMNS must be a
                   postive integer and greater than zero

-f FORMAT      The output format. Can be plain or html

-u             Prints uppercased hex numbers

### Example usage

Note that the examples assume that you are using the bash shell.

___
Printing a hexdump from file.txt:

$ phphd -c 8 file.txt

___
Printing an uppercased hexdump from stdin:

$ phphd -u
    test
    ^D

or:

$ phphd -u <<<EOF
    test
    EOF

Hexdump

Hexdump Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Hexdump

Hexdump Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README