dBase

目录

Note:

此扩展已被移至 » PECL 资源库且不再与 PHP 捆绑。5.3.0.

These functions allow you to access records stored in dBase-format (dbf) databases.

Warning

We recommend against using dBase files as your production database. Use » SQLite or choose any real SQL server instead; » MySQL or » Postgres are common choices with PHP. dBase support is here to allow you to import and export data to and from your web database, because the file format is commonly understood by Windows spreadsheets and organizers.

Caution

As of dbase 7.0.0 the databases are automatically locked via flock. There has been no support for locking earlier, so two concurrent web server processes modifying the same dBase file would have very likely ruined your database. This can happen even with dbase 7.0.0+ on systems which implement the locks at the process level with multithreaded SAPIs such as ISAPI.

dBase files are simple sequential files of fixed length records. Records are appended to the end of the file and deleted records are kept until you call dbase_pack.

Only dbf file levels 3 (dBASE III+) - 5 (dBASE V) are supported. The types of dBase fields available are:

FielddBase TypeFormatAdditional information
MMemon/aThis type is not supported by PHP, such field will be ignored
DDateYYYYMMDDThe field length is limited to 8
TDateTimeYYYYMMDDhhmmss.uuu(FoxPro) No validity checks are done. Available as of dbase 7.0.0.
NNumberA numberYou must declare a length and a precision (the number of digits after the decimal point).
FFloatA float numberSame as N. Available as of PHP 5.2.0
CStringA stringYou must declare a length. When retrieving data, the string will be right-padded with spaces to fit the declared length. Overlong strings will be silently truncated when storing data.
LBooleanT or Y for TRUE, F or N for FALSE, ? for uninitialized.As of dbase 7.0.0, returned as a bool (TRUE or FALSE), or NULL for uninitialized fields. Formerly, returned as an int (1 or 0).

Note:

As of dbase 7.0.0 nullable fields are supported for DBASE_TYPE_FOXPRO databases. If a field is nullable, passing NULL will set the respective flag, and on later retrieval the field value will be NULL.

Note:

There is no support for indexes or memo fields.

安装/配置

目录

需求

构建此扩展不需要其他扩展。

安装

安装此 PECL 扩展相关的信息可在手册中标题为 PECL 扩展的安装章节中找到。更多信息如新的发行版本、下载、源文件、 维护人员信息及变更日志等,都在此处: » https://pecl.php.net/package/dbase.

运行时配置

此扩展没有在 php.ini 中定义配置指令。

资源类型

As of dbase 7.0.0, the resource type dbase is defined, which is returned by dbase_open and dbase_create.

预定义常量

下列常量由此扩展定义,且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

DBASE_VERSION (string)
The extension version. (Available as of dbase 7.0.0)

DBASE_RDONLY (int)
Open database for reading only. Used with dbase_open. (Available as of dbase 7.0.0)

DBASE_RDWR (int)
Open database for reading and writing. Used with dbase_open. (Available as of dbase 7.0.0)

DBASE_TYPE_DBASE (int)
Create dBASE style database. Used with dbase_create. (Available as of dbase 7.0.0)

DBASE_TYPE_FOXPRO (int)
Create FoxPro style database. Used with dbase_create. (Available as of dbase 7.0.0)

范例

Many examples in this reference require a dBase database. We will use /tmp/test.dbf that will be created in the example of dbase_create.

dbase_add_record

Adds a record to a database

说明

bool dbase_add_record ( resource $dbase_identifier , array $record )

Adds the given data to the database.

参数

dbase_identifier
The database link identifier, returned by dbase_open or dbase_create.

record
An indexed array of data. The number of items must be equal to the number of fields in the database, otherwise dbase_add_record will fail.

Note:

If you're using dbase_get_record return value for this parameter, remember to reset the key named deleted.

返回值

成功时返回 TRUE, 或者在失败时返回 FALSE

更新日志

版本说明
dbase 7.0.0dbase_identifier is now a resource instead of an int.

范例

示例 #1 Inserting a record in a dBase database

<?php

// open in read-write mode
$db = dbase_open('/tmp/test.dbf', 2);

if ($db) {
  dbase_add_record($db, array(
      date('Ymd'), 
      'Maxim Topolov', 
      '23', 
      'max@example.com',
      'T'));   
  dbase_close($db);
}

?>

参见

  • dbase_delete_record
  • dbase_replace_record

dbase_close

Closes a database

说明

bool dbase_close ( resource $dbase_identifier )

Closes the given database link identifier.

参数

dbase_identifier
The database link identifier, returned by dbase_open or dbase_create.

返回值

成功时返回 TRUE, 或者在失败时返回 FALSE

更新日志

版本说明
dbase 7.0.0dbase_identifier is now a resource instead of an int.

范例

示例 #1 Closing a dBase database file

<?php

// open in read-only mode
$db = dbase_open('/tmp/test.dbf', 0);

if ($db) {
  // read some data ..
  
  dbase_close($db);
}

?>

参见

  • dbase_open
  • dbase_create

dbase_create

Creates a database

说明

resource dbase_create ( string $filename , array $fields [, int $type = DBASE_TYPE_DBASE ] )

dbase_create creates a dBase database with the given definition. If the file already exists, it is not truncated. dbase_pack can be called to force truncation.

Note: 当启用 安全模式时, PHP 会检查被操作的文件或目录是否与被执行的脚本有相同的 UID(所有者)。

Note:

此函数受 open_basedir 影响。

参数

filename
The name of the database. It can be a relative or absolute path to the file where dBase will store your data.

fields
An array of arrays, each array describing the format of one field of the database. Each field consists of a name, a character indicating the field type, and optionally, a length, a precision and a nullable flag. The supported field types are listed in the introduction section.

Note:

The fieldnames are limited in length and must not exceed 10 chars.

type
The type of database to be created. Either DBASE_TYPE_DBASE or DBASE_TYPE_FOXPRO.

返回值

Returns a database link identifier if the database is successfully created, or FALSE if an error occurred.

更新日志

版本说明
dbase 7.0.0The type parameter has been added.
dbase 7.0.0The return value is now a resource instead of an int.

范例

示例 #1 Creating a dBase database file

<?php

// database "definition"
$def = array(
  array("date",     "D"),
  array("name",     "C",  50),
  array("age",      "N",   3, 0),
  array("email",    "C", 128),
  array("ismember", "L")
);

// creation
if (!dbase_create('/tmp/test.dbf', $def)) {
  echo "Error, can't create the database\n";
}

?>

参见

  • dbase_open
  • dbase_close

dbase_delete_record

Deletes a record from a database

说明

bool dbase_delete_record ( resource $dbase_identifier , int $record_number )

Marks the given record to be deleted from the database.

Note:

To actually remove the record from the database, you must also call dbase_pack.

参数

dbase_identifier
The database link identifier, returned by dbase_open or dbase_create.

record_number
An integer which spans from 1 to the number of records in the database (as returned by dbase_numrecords).

返回值

成功时返回 TRUE, 或者在失败时返回 FALSE

更新日志

版本说明
dbase 7.0.0dbase_identifier is now a resource instead of an int.

参见

  • dbase_add_record
  • dbase_replace_record

dbase_get_header_info

Gets the header info of a database

说明

array dbase_get_header_info ( resource $dbase_identifier )

Returns information on the column structure of the given database link identifier.

参数

dbase_identifier
The database link identifier, returned by dbase_open or dbase_create.

返回值

An indexed array with an entry for each column in the database. The array index starts at 0.

Each array element contains an associative array of column information, as described here:

name
The name of the column

type
The human-readable name for the dbase type of the column (i.e. date, boolean, etc.) The supported field types are listed in the introduction section.

length
The number of bytes this column can hold

precision
The number of digits of decimal precision for the column

format
A suggested printf format specifier for the column

offset
The byte offset of the column from the start of the row

If the database header information cannot be read, FALSE is returned.

更新日志

版本说明
dbase 7.0.0dbase_identifier is now a resource instead of an int.

范例

示例 #1 Showing header information for a dBase database file

<?php
// Path to dbase file
$db_path = "/tmp/test.dbf";

// Open dbase file
$dbh = dbase_open($db_path, 0)
  or die("Error! Could not open dbase database file '$db_path'.");

// Get column information
$column_info = dbase_get_header_info($dbh);

// Display information
print_r($column_info);
?>

dbase_get_record_with_names

Gets a record from a database as an associative array

说明

array dbase_get_record_with_names ( resource $dbase_identifier , int $record_number )

Gets a record from a dBase database as an associative array.

参数

dbase_identifier
The database link identifier, returned by dbase_open or dbase_create.

record_number
The index of the record between 1 and dbase_numrecords($dbase_identifier).

返回值

An associative array with the record. This will also include a key named deleted which is set to 1 if the record has been marked for deletion (see dbase_delete_record). Therefore it is not possible to retrieve the value of a field named deleted with this function.

Each field is converted to the appropriate PHP type, except:

  • Dates are left as strings.
  • DateTime values are converted to strings.
  • Integers outside the range PHP_INT_MIN..PHP_INT_MAX are returned as strings.
  • Before dbase 7.0.0, booleans (L) were converted to 1 or 0.

On error, dbase_get_record_with_names will return FALSE.

更新日志

版本说明
dbase 7.0.0dbase_identifier is now a resource instead of an int.

范例

示例 #1 Listing all the registered members in the database

<?php
// open in read-only mode
$db = dbase_open('/tmp/test.dbf', 0);

if ($db) {
  $record_numbers = dbase_numrecords($db);
  for ($i = 1; $i <= $record_numbers; $i++) {
      $row = dbase_get_record_with_names($db, $i);
      if ($row['ismember'] == 1) {
          echo "Member #$i: " . trim($row['name']) . "\n";
      }
  }
}
?>

参见

  • dbase_get_record

dbase_get_record

Gets a record from a database as an indexed array

说明

array dbase_get_record ( resource $dbase_identifier , int $record_number )

Gets a record from a database as an indexed array.

参数

dbase_identifier
The database link identifier, returned by dbase_open or dbase_create.

record_number
The index of the record between 1 and dbase_numrecords($dbase_identifier).

返回值

An indexed array with the record. This array will also include an associative key named deleted which is set to 1 if the record has been marked for deletion (see dbase_delete_record).

Each field is converted to the appropriate PHP type, except:

  • Dates are left as strings.
  • DateTime values are converted to strings.
  • Integers outside the range PHP_INT_MIN..PHP_INT_MAX are returned as strings.
  • Before dbase 7.0.0, booleans (L) were converted to 1 or 0.

On error, dbase_get_record will return FALSE.

更新日志

版本说明
dbase 7.0.0dbase_identifier is now a resource instead of an int.

参见

  • dbase_get_record_with_names

dbase_numfields

Gets the number of fields of a database

说明

int dbase_numfields ( resource $dbase_identifier )

Gets the number of fields (columns) in the specified database.

Note:

Field numbers are between 0 and dbase_numfields($db)-1, while record numbers are between 1 and dbase_numrecords($db).

参数

dbase_identifier
The database link identifier, returned by dbase_open or dbase_create.

返回值

The number of fields in the database, or FALSE if an error occurs.

更新日志

版本说明
dbase 7.0.0dbase_identifier is now a resource instead of an int.

范例

示例 #1 dbase_numfields Example

<?php

$rec = dbase_get_record($db, $recno);
$nf  = dbase_numfields($db);
for ($i = 0; $i < $nf; $i++) {
  echo $rec[$i], "\n";
}

?>

参见

  • dbase_numrecords

dbase_numrecords

Gets the number of records in a database

说明

int dbase_numrecords ( resource $dbase_identifier )

Gets the number of records (rows) in the specified database.

Note:

Records which are marked as deleted are counted as well.

Note:

Record numbers are between 1 and dbase_numrecords($db), while field numbers are between 0 and dbase_numfields($db)-1.

参数

dbase_identifier
The database link identifier, returned by dbase_open or dbase_create.

返回值

The number of records in the database, or FALSE if an error occurs.

更新日志

版本说明
dbase 7.0.0dbase_identifier is now a resource instead of an int.

范例

示例 #1 Looping over all the records of the database

<?php

// open in read-only mode
$db = dbase_open('/tmp/test.dbf', 0);

if ($db) {
  $record_numbers = dbase_numrecords($db);
  for ($i = 1; $i <= $record_numbers; $i++) {
      $record = dbase_get_record($db, $i);
      if (!$record['deleted']) {
          // do something with the $record
      } else {
          // do something with the deleted $record or ignore it
      }
  }
}

?>

参见

  • dbase_numfields

dbase_open

Opens a database

说明

resource dbase_open ( string $filename , int $mode )

dbase_open opens a dBase database with the given access mode.

Note: 当启用 安全模式时, PHP 会检查被操作的文件或目录是否与被执行的脚本有相同的 UID(所有者)。

Note:

此函数受 open_basedir 影响。

参数

filename
The name of the database. It can be a relative or absolute path to the file where dBase will store your data.

mode
An integer which correspond to those for the open() system call (Typically 0 means read-only, 1 means write-only, and 2 means read and write).

Note:

You can't open a dBase file in write-only mode as the function will fail to read the headers information and thus you can't use 1 as mode.

As of dbase 7.0.0 you can use DBASE_RDONLY and DBASE_RDWR, respectively, to specify the mode.

更新日志

版本说明
dbase 7.0.0The return value is now a resource instead of an int.

范例

示例 #1 Opening a dBase database file

<?php

// open in read-only mode
$db = dbase_open('/tmp/test.dbf', 0);

if ($db) {
  // read some data ..
  
  dbase_close($db);
}

?>

返回值

Returns a database link identifier if the database is successfully opened, or FALSE if an error occurred.

参见

  • dbase_create
  • dbase_close

dbase_pack

Packs a database

说明

bool dbase_pack ( resource $dbase_identifier )

Packs the specified database by permanently deleting all records marked for deletion using dbase_delete_record. Note that the file will be truncated after successful packing (contrary to dBASE III's PACK command).

参数

dbase_identifier
The database link identifier, returned by dbase_open or dbase_create.

返回值

成功时返回 TRUE, 或者在失败时返回 FALSE

更新日志

版本说明
dbase 7.0.0dbase_identifier is now a resource instead of an int.

范例

示例 #1 Emptying a dBase database

<?php

// open in read-write mode
$db = dbase_open('/tmp/test.dbf', 2);

if ($db) {
  $record_numbers = dbase_numrecords($db);
  for ($i = 1; $i <= $record_numbers; $i++) {
      dbase_delete_record($db, $i);
  }
  // expunge the database
  dbase_pack($db);
}

?>

参见

  • dbase_delete_record

dbase_replace_record

Replaces a record in a database

说明

bool dbase_replace_record ( resource $dbase_identifier , array $record , int $record_number )

Replaces the given record in the database with the given data.

参数

dbase_identifier
The database link identifier, returned by dbase_open or dbase_create.

record
An indexed array of data. The number of items must be equal to the number of fields in the database, otherwise dbase_replace_record will fail.

Note:

If you're using dbase_get_record return value for this parameter, remember to reset the key named deleted.

record_number
An integer which spans from 1 to the number of records in the database (as returned by dbase_numrecords).

返回值

成功时返回 TRUE, 或者在失败时返回 FALSE

更新日志

版本说明
dbase 7.0.0dbase_identifier is now a resource instead of an int.

范例

示例 #1 Updating a record in the database

<?php

// open in read-write mode
$db = dbase_open('/tmp/test.dbf', 2);

if ($db) {
  // gets the old row
  $row = dbase_get_record_with_names($db, 1);
  
  // remove the 'deleted' entry
  unset($row['deleted']);
  
  // Update the date field with the current timestamp
  $row['date'] = date('Ymd');
  
  // convert the row to an indexed array
  $row = array_values($row);

  // Replace the record
  dbase_replace_record($db, $row, 1);
  dbase_close($db);
}

?>

注释

Note:

Boolean fields result in an integer element value (0 or 1) when retrieved via class="function">dbase_get_record or class="function">dbase_get_record_with_names. If they are written back, this results in the value becoming 0, so care has to be taken to properly adjust the values.

参见

  • dbase_add_record
  • dbase_delete_record

目录