[ Index ]

PHP Cross Reference of DokuWiki

title

Body

[close]

/inc/ChangeLog/ -> ChangeLog.php (summary)

ChangeLog Prototype; methods for handling changelog

File Size: 678 lines (25 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 14 functions

  __construct()
  isCurrentRevision()
  isLastRevision()
  currentRevision()
  lastRevision()
  cacheRevisionInfo()
  getRevisionInfo()
  getRevisions()
  getRelativeRevision()
  getRevisionsAround()
  getLastRevisionAt()
  retrieveRevisionsAround()
  getCurrentRevisionInfo()
  traceCurrentRevision()

Functions
Functions that are not part of a class:

__construct($id, $chunk_size = 8192)   X-Ref
Constructor

param: string $id page id
param: int $chunk_size maximum block size read from file

isCurrentRevision($rev)   X-Ref
Check whether given revision is the current page

param: int $rev timestamp of current page
return: bool true if $rev is current revision, otherwise false

isLastRevision($rev = null)   X-Ref
Checks if the revision is last revision

param: int $rev revision timestamp
return: bool true if $rev is last revision, otherwise false

currentRevision()   X-Ref
Return the current revision identifier

The "current" revision means current version of the page or media file. It is either
identical with or newer than the "last" revision, that depends on whether the file
has modified, created or deleted outside of DokuWiki.
The value of identifier can be determined by timestamp as far as the file exists,
otherwise it must be assigned larger than any other revisions to keep them sortable.

return: int|false revision timestamp

lastRevision()   X-Ref
Return the last revision identifier, date value of the last entry of the changelog

return: int|false revision timestamp

cacheRevisionInfo($info)   X-Ref
Save revision info to the cache pool

param: array $info Revision info structure
return: bool

getRevisionInfo($rev, $retrieveCurrentRevInfo = true)   X-Ref
Get the changelog information for a specific revision (timestamp)

Adjacent changelog lines are optimistically parsed and cached to speed up
consecutive calls to getRevisionInfo. For large changelog files, only the chunk
containing the requested changelog line is read.

param: int $rev revision timestamp
param: bool $retrieveCurrentRevInfo allows to skip for getting other revision info in the
author: Ben Coburn <btcoburn@silicodon.net>
author: Kate Arzamastseva <pshns@ukr.net>
return: bool|array false or array with entries:

getRevisions($first, $num)   X-Ref
Return a list of page revisions numbers

Does not guarantee that the revision exists in the attic,
only that a line with the date exists in the changelog.
By default the current revision is skipped.

The current revision is automatically skipped when the page exists.
See $INFO['meta']['last_change'] for the current revision.
A negative $first let read the current revision too.

For efficiency, the log lines are parsed and cached for later
calls to getRevisionInfo. Large changelog files are read
backwards in chunks until the requested number of changelog
lines are received.

param: int $first skip the first n changelog lines
param: int $num number of revisions to return
author: Ben Coburn <btcoburn@silicodon.net>
author: Kate Arzamastseva <pshns@ukr.net>
return: array with the revision timestamps

getRelativeRevision($rev, $direction)   X-Ref
Get the nth revision left or right-hand side  for a specific page id and revision (timestamp)

For large changelog files, only the chunk containing the
reference revision $rev is read and sometimes a next chunk.

Adjacent changelog lines are optimistically parsed and cached to speed up
consecutive calls to getRevisionInfo.

param: int $rev revision timestamp used as start date
param: int $direction give position of returned revision with respect to $rev;
return: bool|int

getRevisionsAround($rev1, $rev2, $max = 50)   X-Ref
Returns revisions around rev1 and rev2
When available it returns $max entries for each revision

param: int $rev1 oldest revision timestamp
param: int $rev2 newest revision timestamp (0 looks up last revision)
param: int $max maximum number of revisions returned
return: array with two arrays with revisions surrounding rev1 respectively rev2

getLastRevisionAt($date_at)   X-Ref
Return an existing revision for a specific date which is
the current one or younger or equal then the date

param: number $date_at timestamp
return: string revision ('' for current)

retrieveRevisionsAround($rev, $max)   X-Ref
Collect the $max revisions near to the timestamp $rev

Ideally, half of retrieved timestamps are older than $rev, another half are newer.
The returned array $requestedRevs may not contain the reference timestamp $rev
when it does not match any revision value recorded in changelog.

param: int $rev revision timestamp
param: int $max maximum number of revisions to be returned
return: bool|array

getCurrentRevisionInfo()   X-Ref
Get the current revision information, considering external edit, create or deletion

When the file has not modified since its last revision, the information of the last
change that had already recorded in the changelog is returned as current change info.
Otherwise, the change information since the last revision caused outside DokuWiki
should be returned, which is referred as "external revision".

The change date of the file can be determined by timestamp as far as the file exists,
however this is not possible when the file has already deleted outside of DokuWiki.
In such case we assign 1 sec before current time() for the external deletion.
As a result, the value of current revision identifier may change each time because:
1) the file has again modified outside of DokuWiki, or
2) the value is essentially volatile for deleted but once existed files.

author: Satoshi Sahara <sahara.satoshi@gmail.com>
return: bool|array false when page had never existed or array with entries:

traceCurrentRevision($rev)   X-Ref
Mechanism to trace no-actual external current revision

param: int $rev