fwrite

Binary-safe file write

&reftitle.description; ``int``false```fwrite` `resource` `stream` `string` `data` ``int``null```length`&null;

`fwrite` writes the contents of `data` to the file stream pointed to by `stream`.

&reftitle.parameters;

`stream`

- &fs.file.pointer;

`data`

- The string that is to be written.

`length`

- If `length` is an &integer;, writing will stop after `length` bytes have been written or the end of `data` is reached, whichever comes first.

&reftitle.returnvalues;

`fwrite` returns the number of bytes written, &return.falseforfailure;.

&reftitle.errors;

`fwrite` raises `E_WARNING` on failure.

&reftitle.changelog;

&Version; | &Description;
8.0.0 | `length` is nullable now.

&reftitle.examples;

### A simple `fwrite` example

    <?php
    $filename = 'test.txt';
    $somecontent = "Add this to the file\n";

    // Let's make sure the file exists and is writable first.
    if (is_writable($filename)) {

        // In our example we're opening $filename in append mode.
        // The file pointer is at the bottom of the file hence
        // that's where $somecontent will go when we fwrite() it.
        if (!$fp = fopen($filename, 'a')) {
             echo "Cannot open file ($filename)";
             exit;
        }

        // Write $somecontent to our opened file.
        if (fwrite($fp, $somecontent) === FALSE) {
            echo "Cannot write to file ($filename)";
            exit;
        }

        echo "Success, wrote ($somecontent) to file ($filename)";

        fclose($fp);

    } else {
        echo "The file $filename is not writable";
    }
    ?>

&reftitle.notes;

Writing to a network stream may end before the whole string is written. Return value of `fwrite` may be checked:

    <?php
    function fwrite_stream($fp, $string) {
        for ($written = 0; $written < strlen($string); $written += $fwrite) {
            $fwrite = fwrite($fp, substr($string, $written));
            if ($fwrite === false) {
                return $written;
            }
        }
        return $written;
    }
    ?>

On systems which differentiate between binary and text files (i.e. Windows) the file must be opened with 'b' included in `fopen` mode parameter.

If `stream` was `fopen`ed in append mode, `fwrite`s are atomic (unless the size of `data` exceeds the filesystem's block size, on some platforms, and as long as the file is on a local filesystem). That is, there is no need to `flock` a resource before calling `fwrite`; all of the data will be written without interruption.

If writing twice to the file pointer, then the data will be appended to the end of the file content:

    <?php
    $fp = fopen('data.txt', 'w');
    fwrite($fp, '1');
    fwrite($fp, '23');
    fclose($fp);

    // the content of 'data.txt' is now 123 and not 23!
    ?>

&reftitle.seealso;

- `fread`
- `fopen`
- `fsockopen`
- `popen`
- `file_get_contents`
- `pack`