sha1_file()

Purpose

sha1_file() reads a file and returns the SHA-1 digest of its contents. It is the file-based counterpart of sha1(): instead of hashing a string you already hold in memory, you give it a path, and PHP reads the data for you. Only the bytes matter. The file name, location and modification time have no effect on the result.

Typical uses are spotting accidental changes, building cache keys for generated assets, and comparing a download against a published checksum. SHA-1 is not collision resistant, so it is a poor choice when an attacker could craft the input. For anything security related, use hash_file() with a modern algorithm such as sha256.

Signature

Parameters and defaults

• $filename: the path of the file to hash. It is required. PHP opens it through its stream layer, so wrappers such as php://memory are accepted as well as ordinary paths.
• $binary: optional, default false. With false you get a 40-character lowercase hexadecimal string. With true you get the raw digest, which is 20 bytes long.

Return value and failure cases

On success the function returns a string, either hex or raw bytes depending on $binary. On failure it returns false. A missing file, a directory, or a file you lack permission to read are typical causes. A failed open also raises a warning. Always test the result with the strict comparison === false, because a string result should never be treated loosely as a boolean.

Example 1: the digest of empty content

The examples on this page use the in-memory php://memory stream, which starts out empty, so the results are fully predictable. Hashing empty content gives the well-known SHA-1 value that begins with da39a3ee.

<?php
echo sha1_file('php://memory') . "\n";

da39a3ee5e6b4b0d3255bfef95601890afd80709

Example 2: agreement with sha1()

sha1_file() and sha1() use the same algorithm. Hashing a stream with no bytes must therefore match hashing an empty string.

<?php
var_dump(sha1_file('php://memory') === sha1(''));

bool(true)

Example 3: binary output

With the second argument set to true, the digest is 20 raw bytes. Converting those bytes with bin2hex() gives the same text as the default hex form.

<?php
$raw = sha1_file('php://memory', true);
echo json_encode([strlen($raw), bin2hex($raw) === sha1('')]) . PHP_EOL;

[20,true]

Edge cases

• Empty content is valid input. It produces a normal digest, not false.
• Raw output is not printable. The 20 bytes may include control characters or invalid UTF-8. Convert them with bin2hex() or base64_encode() before logging them or putting them in JSON.
• Directories fail. Passing a directory path does not produce a hash, so check for false.
• Large files are read through a stream, so you do not need to load the whole file into a PHP string yourself. If you need to hash data arriving in pieces, hash_init() with hash_update() is the incremental alternative.
• Content only. Two files with different names but identical bytes give the same digest.

Common mistakes

1. Using SHA-1 for passwords or trust decisions. It is neither a password hash nor a safe integrity check against an adversary. Use password_hash() for passwords and hash_file('sha256', ...) for stronger checksums.
2. Forgetting the failure type. Code such as if (sha1_file($p)) is sloppy. Write $h = sha1_file($p); if ($h === false) { ... }.
3. Printing the binary form directly. Raw digests look like garbage in a browser or terminal. Use the default hex form for display.
4. Comparing digests with a loose or early-exit check when the value is secret. Use hash_equals() for that situation.
5. Hashing a path string by mistake. sha1('/tmp/report.txt') hashes the characters of the path, not the file. Use sha1_file() to hash the contents.

Related functions

• sha1() hashes a string in memory.
• hash_file() hashes a file with a chosen algorithm.
• hash_init() starts an incremental hashing context for chunked data.
• md5_file() is the MD5 equivalent and shares the same caveats.

Recap

sha1_file($filename, $binary) returns a 40-character hex digest of a file's bytes, or a 20-byte raw digest when $binary is true. It returns false and emits a warning when the file cannot be read, so check with === false. It suits quick change detection but not security-sensitive work, where hash_file() with SHA-256 is the better tool.