【PHP8.x】SplTempFileObject::ftell()メソッドの使い方

ftellメソッドの使い方について、初心者にもわかりやすく解説します。

作成日: 2025年09月11日更新日: 2026年01月06日

基本的な使い方

ftellメソッドは、SplTempFileObjectクラスに属し、そのオブジェクトが表すファイルポインタの現在位置を取得するメソッドです。SplTempFileObjectは、一時的なファイルをメモリ上や実際のディスク上に作成し、通常のファイルと同じようにデータの読み書きができるようにする特別なクラスです。

このftellメソッドは、一時ファイル内のどこまで読み書きが進んだかを示す「ファイルポインタ」の位置を、ファイルの先頭からのバイト単位のオフセットで返します。ファイルの先頭が0バイト目となり、そこから何バイト進んだかを示す整数値です。

例えば、ファイルを順次読み込んでいる際に現在の読み込み位置を確認したい場合や、特定の場所から再度データを読み込みたい場合などに利用されます。ファイルの一部を繰り返し処理する際や、途中で処理を中断した後に再開する位置を特定するのに役立ちます。また、fseekメソッドと組み合わせることで、ファイル内の任意の位置へファイルポインタを移動させることも可能になります。

ファイルポインタが取得できない場合や、何らかのエラーが発生した場合は、ブール値のfalseが返されます。これにより、ファイル操作の途中でのエラー検出にも役立ちます。ftellメソッドは、ファイル処理の正確な制御と柔軟なデータアクセスを実現するために不可欠な機能を提供します。

構文(syntax)


1<?php
2$tempFileObject = new SplTempFileObject();
3$currentPosition = $tempFileObject->ftell();
4?>

引数(parameters)

引数なし

引数はありません

戻り値(return)

int|false

現在のファイルポインタのオフセットをバイト単位で返します。失敗した場合は false を返します。

サンプルコード

SplTempFileObjectのftellでファイルポインタ位置を取得する


1<?php
2
3// SplTempFileObject は、一時ファイルとして機能するオブジェクトです。
4// 'php://memory' を指定することで、ファイルがメモリ上に作成され、
5// 実際のディスクI/Oなしで操作できます。
6$tempFile = new SplTempFileObject('php://memory');
7
8// ファイルにデータを書き込みます。
9// この操作により、ファイルポインタが書き込まれたデータの末尾に移動します。
10$testData = "Hello, PHP ftell!\n";
11$bytesWritten = $tempFile->fwrite($testData);
12
13// ftell() メソッドを使用して、現在のファイルポインタの位置を取得します。
14// 書き込み後、ポインタはデータのバイト数に相当する位置にあるはずです。
15$currentPosition = $tempFile->ftell();
16
17if ($currentPosition !== false) {
18    echo "ファイルに " . $bytesWritten . " バイト書き込みました。\n";
19    echo "現在のファイルポインタの位置: " . $currentPosition . " バイト\n";
20} else {
21    echo "ftell() の実行に失敗しました。\n";
22}
23
24// ファイルポインタをファイルの先頭 (0バイト目) に移動します。
25$tempFile->fseek(0);
26
27// 再び ftell() を使用して、ファイルポインタの新しい位置を確認します。
28// fseek(0) の後なので、位置は 0 であるはずです。
29$newPosition = $tempFile->ftell();
30
31if ($newPosition !== false) {
32    echo "ファイルポインタを先頭に移動しました。\n";
33    echo "新しいファイルポインタの位置: " . $newPosition . " バイト\n";
34} else {
35    echo "ftell() (移動後) の実行に失敗しました。\n";
36}
37
38// ファイルポインタを移動した後、ファイルを読み込んでみます。
39// ここでは最初の5バイトを読み込みます。
40$readData = $tempFile->fread(5);
41echo "先頭から " . strlen($readData) . " バイト読み込みました: '" . $readData . "'\n";
42
43// 読み込み後、ファイルポインタがどこにあるか再度 ftell() で確認します。
44$positionAfterRead = $tempFile->ftell();
45if ($positionAfterRead !== false) {
46    echo "読み込み後のファイルポインタの位置: " . $positionAfterRead . " バイト\n";
47} else {
48    echo "ftell() (読み込み後) の実行に失敗しました。\n";
49}
50
51?>

このPHPのサンプルコードは、メモリ上で一時ファイルを扱うSplTempFileObjectクラスと、そのftell()メソッドの利用方法を示しています。ftell()は、ファイルポインタが現在ファイル内のどの位置にあるかをバイト単位で取得するメソッドです。引数はなく、成功時にはファイルポインタの位置を整数値で、失敗時にはfalseを返します。

まず、SplTempFileObject('php://memory')でメモリ上の一時ファイルオブジェクトを作成し、fwrite()でデータを書き込みます。データを書き込むと、ファイルポインタは自動的に書き込んだデータの末尾に移動します。最初のftell()では、この書き込み後のポインタ位置が、書き込んだデータのバイト数と一致することを確認しています。

次に、fseek(0)を使用してファイルポインタをファイルの先頭（0バイト目）に移動させます。移動後、再度ftell()を呼び出すことで、ファイルポインタが正しく先頭にあることを確認できます。

さらに、fread()でファイルからデータを読み込むと、読み込んだバイト数分だけファイルポインタが移動します。最後のftell()では、この読み込み後のファイルポインタの位置を確認し、ftell()がファイルの操作に応じて正確な位置を返すことを示しています。このように、ftell()はファイルの読み書き操作における現在の位置を把握するために利用されます。

ftell()メソッドは、ファイルポインタの現在位置をバイト単位で返しますが、操作に失敗するとfalseを返します。そのため、戻り値がfalseでないか、常に厳密に確認する処理を記述することが重要です。サンプルコードのように!== falseで型も含めて比較することで、安全に利用できます。

ファイルへの書き込み（fwrite）や読み込み（fread）を行うと、ファイルポインタは自動的に移動します。もし特定の位置から操作を再開したい場合は、fseek()メソッドを使ってポインタを目的の場所へ明示的に移動させてください。ftell()はファイルポインタの位置を教えてくれる便利な機能ですが、ポインタがどこにあるかを常に意識しながらコードを書くことが、予期せぬ動作を防ぐ鍵となります。