Book/dbase-Phpdoc专题

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 <span class="function">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.

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:

Field dBase Type Format Additional information
M Memo n/a This type is not supported by PHP, such field will be ignored
D Date YYYYMMDD The field length is limited to 8
T DateTime YYYYMMDDhhmmss.uuu (FoxPro) No validity checks are done. Available as of dbase 7.0.0.
N Number A number You must declare a length and a precision (the number of digits after the decimal point).
F Float A float number Same as N. Available as of PHP 5.2.0
C String A string You 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.
L Boolean T 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 <span class="function">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 <span class="function">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 <span class="function">dbase_create. (Available as of dbase 7.0.0)

DBASE_TYPE_FOXPRO (int)
Create FoxPro style database. Used with <span class="function">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 <span class="function">dbase_create.

dbase_add_record

Adds a record to a database

说明

bool <span class="methodname">dbase_add_record ( <span class="methodparam">resource $database , <span class="type">array $data )

Adds the given data to the database.

参数

database
The database resource, returned by <span class="function">dbase_open or <span class="function">dbase_create.

data
An indexed array of data. The number of items must be equal to the number of fields in the database, otherwise <span class="function">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.0 database 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', 
      '[email protected]',
      'T'));   
  dbase_close($db);
}

?>

参见

  • dbase_delete_record
  • dbase_replace_record

dbase_close

Closes a database

说明

bool <span class="methodname">dbase_close ( <span class="type">resource $database )

Closes the given database resource.

参数

database
The database resource, returned by <span class="function">dbase_open or <span class="function">dbase_create.

返回值

成功时返回 true， 或者在失败时返回 false。

更新日志

版本 说明
dbase 7.0.0 database 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 <span class="methodname">dbase_create ( <span class="methodparam">string $path , array $fields [, <span class="type">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:

此函数受 open_basedir 影响。

参数

path
The path 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 resource if the database is successfully created, or false if an error occurred.

更新日志

版本 说明
dbase 7.0.0 The type parameter has been added.
dbase 7.0.0 The 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 <span class="methodname">dbase_delete_record ( <span class="methodparam">resource $database , <span class="type">int $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.

参数

database
The database resource, returned by <span class="function">dbase_open or <span class="function">dbase_create.

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.0 database 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 <span class="methodname">dbase_get_header_info ( <span class="methodparam">resource $database )

Returns information on the column structure of the given database resource.

参数

database
The database resource, returned by <span class="function">dbase_open or <span class="function">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.0 database 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 <span class="methodname">dbase_get_record_with_names ( <span class="methodparam">resource $database , <span class="type">int $number )

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

参数

database
The database resource, returned by <span class="function">dbase_open or <span class="function">dbase_create.

_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.

每个字段都会被转换为对应的 PHP 类型，除了以下场景：

  • 日期会被转换成字符串。
  • DateTime 会被转换成字符串。
  • 范围之外的整数 PHP_INT_MIN..PHP_INT_MAX 将返回字符串。
  • dbase 7.0.0 之前的版本， 布尔型 (L) 将被转换为 1 或 0。

On error, dbase_get_record_with_names will return false.

更新日志

版本 说明
dbase 7.0.0 database 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 <span class="methodname">dbase_get_record ( <span class="methodparam">resource $database , <span class="type">int $number )

Gets a record from a database as an indexed array.

参数

database
The database resource, returned by <span class="function">dbase_open or <span class="function">dbase_create.

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 <span class="function">dbase_delete_record).

每个字段都会被转换为对应的 PHP 类型，除了以下场景：

  • 日期会被转换成字符串。
  • DateTime 会被转换成字符串。
  • 范围之外的整数 PHP_INT_MIN..PHP_INT_MAX 将返回字符串。
  • dbase 7.0.0 之前的版本， 布尔型 (L) 将被转换为 1 或 0。

On error, dbase_get_record will return false.

更新日志

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

参见

  • dbase_get_record_with_names

dbase_numfields

Gets the number of fields of a database

说明

int <span class="methodname">dbase_numfields ( <span class="methodparam">resource $database )

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).

参数

database
The database resource, returned by <span class="function">dbase_open or <span class="function">dbase_create.

返回值

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

更新日志

版本 说明
dbase 7.0.0 database 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 <span class="methodname">dbase_numrecords ( <span class="methodparam">resource $database )

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.

参数

database
The database resource, returned by <span class="function">dbase_open or <span class="function">dbase_create.

返回值

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

更新日志

版本 说明
dbase 7.0.0 database 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<span class="type">false <span class="methodname">dbase_open ( <span class="type">string $path , <span class="methodparam">int $mode )

dbase_open opens a dBase database with the given access mode.

Note:

此函数受 open_basedir 影响。

参数

path
The path 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.

返回值

Returns a database resource on success, 或者在失败时返回 false.

更新日志

版本 说明
dbase 7.0.0 The 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);
}

?>

参见

  • dbase_create
  • dbase_close

dbase_pack

Packs a database

说明

bool <span class="methodname">dbase_pack ( <span class="type">resource $database )

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).

参数

database
The database resource, returned by <span class="function">dbase_open or <span class="function">dbase_create.

返回值

成功时返回 true， 或者在失败时返回 false。

更新日志

版本 说明
dbase 7.0.0 database 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 <span class="methodname">dbase_replace_record ( <span class="methodparam">resource $database , <span class="type">array $data , <span class="methodparam">int $number )

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

参数

database
The database resource, returned by <span class="function">dbase_open or <span class="function">dbase_create.

data
An indexed array of data. The number of items must be equal to the number of fields in the database, otherwise <span class="function">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.

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.0 database 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 int element value (0 or 1) when retrieved via <span class="function">dbase_get_record or <span 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

目录

本站为非盈利网站，作品由网友提供上传，如无意中有侵犯您的版权，请联系删除