ExcelBook.php

<?php
/*
  +---------------------------------------------------------------------------+
  | ExcelBook                                                                 |
  |                                                                           |
  | Reference file for NuSphere PHPEd (and possibly other IDE's) for use with |
  | php_excel interface to libxl by Ilia Alshanetsky <ilia@ilia.ws>           |
  |                                                                           |
  | php_excel "PECL" style module (http://github.com/iliaal/php_excel)        |
  | libxl library (http://www.libxl.com)                                      |
  |                                                                           |
  | Rob Gagnon <rgagnon24@gmail.com>                                          |
  +---------------------------------------------------------------------------+
*/
class ExcelBook
{
	const PICTURETYPE_PNG = 0;
	const PICTURETYPE_JPEG = 1;
	const PICTURETYPE_GIF = 2;
	const PICTURETYPE_WMF = 3;
	const PICTURETYPE_DIB = 4;
	const PICTURETYPE_EMF = 5;
	const PICTURETYPE_PICT = 6;
	const PICTURETYPE_TIFF = 7;
	const PICTURETYPE_SVG = 8;

	const SCOPE_UNDEFINED = -2;
	const SCOPE_WORKBOOK = -1;

	const SHEETTYPE_SHEET = 0;
	const SHEETTYPE_CHART = 1;
	const SHEETTYPE_UNKNOWN = 2;

	const POSITION_MOVE_AND_SIZE = 0;
	const POSITION_ONLY_MOVE = 1;
	const POSITION_ABSOLUTE = 2;

	const CALCMODE_MANUAL = 0;
	const CALCMODE_AUTO = 1;
	const CALCMODE_AUTONOTABLE = 2;

	const CELLSTYLE_NORMAL = 0;
	const CELLSTYLE_BAD = 1;
	const CELLSTYLE_GOOD = 2;
	const CELLSTYLE_NEUTRAL = 3;
	const CELLSTYLE_CALC = 4;
	const CELLSTYLE_CHECKCELL = 5;
	const CELLSTYLE_EXPLANATORY = 6;
	const CELLSTYLE_INPUT = 7;
	const CELLSTYLE_OUTPUT = 8;
	const CELLSTYLE_HYPERLINK = 9;
	const CELLSTYLE_LINKEDCELL = 10;
	const CELLSTYLE_NOTE = 11;
	const CELLSTYLE_WARNING = 12;
	const CELLSTYLE_TITLE = 13;
	const CELLSTYLE_HEADING1 = 14;
	const CELLSTYLE_HEADING2 = 15;
	const CELLSTYLE_HEADING3 = 16;
	const CELLSTYLE_HEADING4 = 17;
	const CELLSTYLE_TOTAL = 18;
	const CELLSTYLE_COMMA = 43;
	const CELLSTYLE_COMMA0 = 44;
	const CELLSTYLE_CURRENCY = 45;
	const CELLSTYLE_CURRENCY0 = 46;
	const CELLSTYLE_PERCENT = 47;

	/**
	* Create a new Excel workbook
	*
	* @param string|null $license_name (optional, default=null)
	* @param string|null $license_key (optional, default=null)
	* @param bool $excel_2007 (optional, default=false)
	* @return ExcelBook
	*/
	public function __construct(?string $license_name = null, ?string $license_key = null, bool $excel_2007 = false)
	{
	}

	/**
	* Returns whether the library requires a license key
	*
	* @return bool
	*/
	public static function requiresKey(): bool
	{
	}

	/**
	* Add or copy an ExcelFont object
	*
	* @param ExcelFont $font (optional, default=null) Font to copy
	* @return ExcelFont|false
	*/
	public function addFont(?ExcelFont $font = null): ExcelFont|false
	{
	}

	/**
	* Add or copy an ExcelFormat object
	*
	* @param ExcelFormat|null $format (optional, default=null) Format to copy
	* @return ExcelFormat|false
	*/
	public function addFormat(?ExcelFormat $format = null): ExcelFormat|false
	{
	}

	/**
	* Get an array of all ExcelFormat objects used inside a workbook
	*
	* @return array|false Array of ExcelFormat objects
	*/
	public function getAllFormats(): array|false
	{
	}

	/**
	* Get the current workbook's Excel error string
	*
	* LibXL load failures occur on a temporary workbook: inspect their warning
	* instead of expecting the load error here. See ExcelBook::load().
	*
	* @return string|false Description of last error, or false if no error
	*/
	public function getError(): string|false
	{
	}

	/**
	* Load Excel from file
	*
	* A successful load replaces the workbook and invalidates existing child
	* wrappers (ExcelSheet, ExcelFont, ExcelFormat, ExcelAutoFilter, ...).
	* Fetch new wrappers after success. A failed load leaves the previous
	* workbook and its live wrappers usable; it does not adopt partial data.
	* This guarantee does not undo changes made by user stream callbacks or
	* error handlers. Exceptions from those callbacks propagate.
	*
	* A LibXL load failure returns false and emits an E_WARNING containing the
	* load error. That error belongs to a temporary workbook and is not retained
	* by getError() or errorCode(). Input validation and stream failures can
	* return false earlier; an empty string returns false without a warning.
	*
	* The filename resolves like fopen(): a "data:" name, or any path while
	* file: is replaced by a user wrapper, is read through that wrapper. Only
	* names PHP opens as plain files are passed to LibXL directly. The same
	* rule applies to loadFilePartially(), loadInfo(), and addPictureFromFile();
	* loadFileWithoutEmptyCells() rejects wrapper names.
	*
	* @note Stream sources are fully buffered (cap UINT_MAX); enforce an app-side size bound first, e.g. `if (filesize($path) > $maxBytes) throw new RuntimeException('spreadsheet too large');`. See SECURITY.md.
	* @param string $filename
	* @return bool
	*/
	public function loadFile(string $filename): bool
	{
	}

	/**
	* Load a row slice from Excel data string
	*
	* @see ExcelBook::load() for success-only wrapper invalidation and failure diagnostics
	*
	* @note Stream sources are fully buffered (cap UINT_MAX); enforce an app-side size bound first. See ExcelBook::loadFile() for an example.
	* @since libxl 5.0.0
	* @param string $data
	* @param int $sheet_index 0-based sheet index to load
	* @param int $row_first First 0-based row to load
	* @param int $row_last Last 0-based row to load
	* @param bool $keep_all_sheets (optional, default=false)
	* @return bool
	*/
	public function loadPartially(string $data, int $sheet_index, int $row_first, int $row_last, bool $keep_all_sheets = false): bool
	{
	}

	/**
	* Load a row slice from Excel file
	*
	* @see ExcelBook::load() for success-only wrapper invalidation and failure diagnostics
	*
	* @since libxl 5.0.0
	* @param string $filename
	* @param int $sheet_index 0-based sheet index to load
	* @param int $row_first First 0-based row to load
	* @param int $row_last Last 0-based row to load
	* @param bool $keep_all_sheets (optional, default=false)
	* @return bool
	*/
	public function loadFilePartially(string $filename, int $sheet_index, int $row_first, int $row_last, bool $keep_all_sheets = false): bool
	{
	}

	/**
	* Load Excel from file without empty cells (xls format only; libxl does not
	* support this for xlsx files and the call fails with a warning on such books)
	*
	* @see ExcelBook::load() for success-only wrapper invalidation and failure diagnostics
	*
	* @since libxl 5.0.0
	* @param string $filename Plain filesystem path
	* @return bool
	*/
	public function loadFileWithoutEmptyCells(string $filename): bool
	{
	}

	/**
	* Load Excel data string
	*
	* A successful load replaces the workbook and invalidates existing child
	* wrappers (ExcelSheet, ExcelFont, ExcelFormat, ExcelAutoFilter, ...).
	* Fetch new wrappers after success. A failed load leaves the previous
	* workbook and its live wrappers usable; it does not adopt partial data.
	* This guarantee does not undo changes made by user stream callbacks or
	* error handlers. Exceptions from those callbacks propagate.
	*
	* A LibXL load failure returns false and emits an E_WARNING containing the
	* load error. That error belongs to a temporary workbook and is not retained
	* by getError() or errorCode(). Input validation and stream failures can
	* return false earlier; an empty string returns false without a warning.
	*
	* @note Stream sources are fully buffered (cap UINT_MAX); enforce an app-side size bound first. See ExcelBook::loadFile() for an example.
	* @param string $data
	* @return bool
	*/
	public function load(string $data): bool
	{
	}

	/**
	* Save Excel file
	*
	* Saves through PHP user-defined stream wrappers write the workbook to a
	* sibling staging URL first. A short or failed staged write leaves the
	* destination untouched and is never retried against it. A rename() method,
	* including one handled by __call(), that fails or throws also fails closed.
	* Without rename() or __call(), a complete staged write falls back to a warned
	* non-atomic direct write. If unlink() is also unavailable, the staging file
	* remains because PHP's adapter advertises both operations anyway.
	* Native stream wrappers without rename/unlink support write directly.
	* A name PHP resolves to a user wrapper takes this route even without
	* "://": data: names, and every plain path while file: is replaced. Such a
	* save writes the workbook as it was when save() was called, even if a
	* wrapper callback reloads or reinitializes this book.
	* With an empty filename, save() returns the workbook as a binary string.
	*
	* @param string $filename (optional, default="") If empty or omitted, returns binary string
	* @return string|bool If $filename is empty or omitted, returns string; otherwise returns bool
	*/
	public function save(string $filename = ''): string|bool
	{
	}

	/**
	* Get an Excel worksheet
	*
	* @param int $sheet_number (optional, default=0) 0-based worksheet number
	* @return ExcelSheet|false
	*/
	public function getSheet(int $sheet = 0): ExcelSheet|false
	{
	}

	/**
	* Get an excel sheet by name
	*
	* @param string $name
	* @param bool $case_insensitive (optional, default=false)
	* @return ExcelSheet|false
	*/
	public function getSheetByName(string $name, bool $case_insensitive = false): ExcelSheet|false
	{
	}

	/**
	* Add a worksheet to a workbook
	*
	* @param string $name The name for the new worksheet
	* @return ExcelSheet|false
	*/
	public function addSheet(string $name): ExcelSheet|false
	{
	}

	/**
	* Create a copy of a worksheet in a workbook
	*
	* @param string $name The name for the new worksheet
	* @param int $sheet_number The 0-based number of the source worksheet to copy
	* @return ExcelSheet|false
	*/
	public function copySheet(string $name, int $sheet_number): ExcelSheet|false
	{
	}

	/**
	* Delete an Excel worksheet
	*
	* On success, all existing ExcelSheet wrappers from this workbook become
	* stale, including surviving sheets and their sheet-owned wrappers
	* (autofilters, filter columns, tables, form controls, conditional formatting).
	* Re-fetch surviving sheets with getSheet() or getSheetByName(), then obtain
	* their children again. Later sheet indexes shift after deletion. Calls on
	* stale wrappers warn and return false; constructors given stale sheet-owned
	* wrappers throw an exception. Workbook-owned fonts and formats remain usable.
	* A failed deletion leaves existing wrappers usable.
	*
	* @see ExcelBook::getSheet()
	* @see ExcelBook::getSheetByName()
	* @param int $sheet 0-based worksheet number to delete
	* @return bool True on success, false on failure
	*/
	public function deleteSheet(int $sheet): bool
	{
	}

	/**
	* Get the number of worksheets inside a workbook
	*
	* @return int|false
	*/
	public function sheetCount(): int|false
	{
	}

	/**
	* Get or set the active Excel worksheet number
	*
	* @see ExcelBook::getActiveSheet()
	* @see ExcelBook::setActiveSheet()
	* @param int $sheet_number (optional) If supplied, the 0-based worksheet number to set as active
	* @return int|false 0-based active worksheet number
	*/
	public function activeSheet(int $sheet = -1): int|false
	{
	}

	/**
	* Get a custom cell format
	*
	* @see ExcelBook::addCustomFormat()
	* @param int $id
	* @return string|false
	*/
	public function getCustomFormat(int $id): string|false
	{
	}

	/**
	* Create a custom cell format
	*
	* @see ExcelBook::getCustomFormat()
	* @param string $format_string
	* @return int|false The ID assigned to the new format
	*/
	public function addCustomFormat(string $format): int|false
	{
	}

	/**
	* Pack a unix timestamp into an Excel double using PHP's configured timezone
	*
	* @see ExcelBook::unpackDate()
	* @param int $timestamp
	* @return float|false
	*/
	public function packDate(int $timestamp): float|false
	{
	}

	/**
	* Pack a date from single values into an Excel double
	*
	* @param int $year
	* @param int $month
	* @param int $day
	* @param int $hour
	* @param int $min
	* @param int $sec
	* @return float|false
	*/
	public function packDateValues(int $year, int $month, int $day, int $hour, int $min, int $sec): float|false
	{
	}

	/**
	* Unpack an Excel double into a unix timestamp using PHP's configured timezone
	*
	* Time-only serials in [0, 1) return seconds since midnight. Calendar dates
	* outside the platform's PHP integer range return false.
	*
	* @see ExcelBook::packDate()
	* @param float $date
	* @return int|false
	*/
	public function unpackDate(float $date): int|false
	{
	}

	/**
	* Get the active worksheet inside a workbook
	*
	* @see ExcelBook::activeSheet()
	* @see ExcelBook::setActiveSheet()
	* @return int|false 0-based active worksheet number
	*/
	public function getActiveSheet(): int|false
	{
	}

	/**
	* Set the active worksheet
	*
	* @see ExcelBook::getActiveSheet()
	* @see ExcelBook::activeSheet()
	* @param int $sheet_number 0-based worksheet to make active
	* @return bool
	*/
	public function setActiveSheet(int $sheet): bool
	{
	}

	/**
	* Get the default font
	*
	* @see ExcelBook::setDefaultFont()
	* @return array|false Array with keys "font"(string) and "font_size"(int)
	*/
	public function getDefaultFont(): array|false
	{
	}

	/**
	* Set the default font and size
	*
	* @see ExcelBook::getDefaultFont()
	* @param string $font
	* @param int $font_size
	* @return void
	*/
	public function setDefaultFont(string $font, int $font_size): mixed
	{
	}

	/**
	* Set the encoding of text passed to and returned by this workbook
	*
	* Every workbook starts in UTF-8 mode: LibXL decodes and encodes text as
	* UTF-8 whatever the process locale is. Call this method only for text in
	* another byte encoding, for example setLocale('de_DE.ISO-8859-1') for
	* Latin-1 strings. LibXL then converts text with the C library under that
	* locale, and switches the process LC_CTYPE to it. Pass "UTF-8" to return
	* to the default.
	*
	* A reload keeps the locale accepted last. If LibXL rejects the locale
	* name, the method emits a warning, returns false, and the workbook keeps
	* its previous locale. An empty string returns false and changes nothing.
	*
	* @param string $locale
	* @return bool
	*/
	public function setLocale(string $locale): mixed
	{
	}

	/**
	* Add a picture from file
	*
	* The filename resolves like fopen(), including "data:" names; see
	* ExcelBook::loadFile().
	*
	* @note Stream sources are fully buffered (cap UINT_MAX); enforce an app-side size bound first. See ExcelBook::loadFile() for an example.
	* @see ExcelBook::addPictureFromString()
	* @see ExcelSheet::addPictureScaled()
	* @see ExcelSheet::addPictureDim()
	* @param string $filename
	* @return int|false A picture ID
	*/
	public function addPictureFromFile(string $filename): int|false
	{
	}

	/**
	* Add a picture from string
	*
	* @see ExcelBook::addPictureFromFile()
	* @see ExcelSheet::addPictureScaled()
	* @see ExcelSheet::addPictureDim()
	* @param string $data
	* @return int|false A picture ID
	*/
	public function addPictureFromString(string $data): int|false
	{
	}

	/**
	* Returns whether RGB mode is active
	*
	* @see ExcelBook::setRGBMode()
	* @return bool
	*/
	public function rgbMode(): bool
	{
	}

	/**
	* Sets RGB mode on or off
	*
	* @see ExcelBook::rgbMode()
	* @param bool $mode
	* @return bool
	*/
	public function setRGBMode(bool $mode): bool
	{
	}

	/**
	* Packs red, green, and blue components in color value. Used for xlsx format only.
	*
	* @see ExcelBook::colorUnpack()
	* @param int $r
	* @param int $g
	* @param int $b
	* @return int|false
	*/
	public function colorPack(int $r, int $g, int $b): int|false
	{
	}

	/**
	* Unpacks an XLS palette color or XLSX color value into red, green, and blue components.
	*
	* @see ExcelBook::colorPack()
	* @param int $color One of ExcelFormat::COLOR_* constants
	* @return array|false Array with keys "red"(int), "green"(int), and "blue"(int), or false with a
	* warning when the color has no RGB value. In xls books only palette colors 8..63 have RGB values;
	* automatic colors such as ExcelFormat::COLOR_DEFAULT_FOREGROUND (0x40), 0x41, and 0x7FFF return false.
	*/
	public function colorUnpack(int $color): array|false
	{
	}

	/**
	* Returns whether the 1904 date system is active
	*
	* @return bool
	*/
	public function isDate1904(): bool
	{
	}

	/**
	* Sets the date system mode
	*
	* @param bool $date_type true for 1904, false for 1900
	* @return bool
	*/
	public function setDate1904(bool $date_type): bool
	{
	}

	/**
	* Returns BIFF version of binary file. Used for xls format only.
	*
	* @return int|false
	*/
	public function biffVersion(): int|false
	{
	}

	/**
	* Sets the R1C1 reference mode
	*
	* @param bool $active
	* @return bool
	*/
	public function setRefR1C1(bool $active): bool
	{
	}

	/**
	* Returns whether the R1C1 reference mode is active
	*
	* @return bool
	*/
	public function getRefR1C1(): bool
	{
	}

	/**
	* Returns a picture at position index
	*
	* @param int $index
	* @return array|false Array with keys "data"(string) and "type"(int); "data" is an empty string for a picture added with addPictureAsLink() without embedding
	*/
	public function getPicture(int $index): array|false
	{
	}

	/**
	* Returns a number of pictures in this workbook
	*
	* @return int|false
	*/
	public function getNumPictures(): int|false
	{
	}

	/**
	* Inserts a new sheet at position index
	*
	* @param int $index
	* @param string $name
	* @param ExcelSheet|null $sheet (optional) Existing sheet from this workbook to copy
	* @return ExcelSheet|false
	*/
	public function insertSheet(int $index, string $name, ?ExcelSheet $sheet = null): ExcelSheet|false
	{
	}

	/**
	* Returns whether the workbook is a template
	*
	* @return bool
	*/
	public function isTemplate(): bool
	{
	}

	/**
	* Sets the template flag
	*
	* @param bool $mode
	* @return bool
	*/
	public function setTemplate(bool $mode): bool
	{
	}

	/**
	* Returns type of sheet with specified index
	*
	* @param int $sheet
	* @return int|false One of ExcelBook::SHEETTYPE_* constants
	*/
	public function sheetType(int $sheet): int|false
	{
	}

	/**
	* Get LibXL version
	*
	* @return string
	*/
	public function getLibXlVersion(): string
	{
	}

	/**
	* Get PHP excel extension version
	*
	* @return string
	*/
	public function getPhpExcelVersion(): string
	{
	}

	/**
	* Adds a picture to the workbook as link (only for xlsx files)
	*
	* @note The path persists as an external relationship (UNC/http included); allowlist caller-supplied paths and never pass untrusted input as the link target.
	* @param string $filename
	* @param bool $insert (optional, default=false) false stores only a link, true stores picture and link
	* @return int|false Picture identifier
	*/
	public function addPictureAsLink(string $filename, bool $insert = false): int|false
	{
	}

	/**
	* Moves a sheet with specified index to a new position
	*
	* @param int $src_index
	* @param int $dest_index
	* @return bool
	*/
	public function moveSheet(int $src_index, int $dest_index): bool
	{
	}

	/**
	* Load Excel sheet info without loading the full file
	*
	* On success the book enters info-only mode: only sheetCount(), getSheetName(),
	* the load*() methods, clear(), __construct(), getLibXlVersion(),
	* getPhpExcelVersion(), and requiresKey() work. Every other ExcelBook method
	* emits a warning and returns false. The ExcelFont, ExcelFormat, ExcelSheet,
	* ExcelRichString, ExcelConditionalFormat, and ExcelCoreProperties constructors
	* throw when given this book. A successful full load*(), clear(), or
	* __construct() call leaves info-only mode.
	*
	* @see ExcelBook::load() for success-only wrapper invalidation and failure diagnostics
	*
	* @note Stream sources are fully buffered (cap UINT_MAX); enforce an app-side size bound first. See ExcelBook::loadFile() for an example.
	* @param string $filename
	* @return bool
	*/
	public function loadInfo(string $filename): bool
	{
	}

	/**
	* Returns the sheet name by index
	*
	* @param int $index
	* @return string|false
	*/
	public function getSheetName(int $index): string|false
	{
	}

	/**
	* Creates a new rich string
	*
	* @return ExcelRichString|false
	*/
	public function addRichString(): ExcelRichString|false
	{
	}

	/**
	* Returns the calculation mode
	*
	* @return int|false One of ExcelBook::CALCMODE_* constants
	*/
	public function calcMode(): int|false
	{
	}

	/**
	* Sets the calculation mode
	*
	* @param int $mode One of ExcelBook::CALCMODE_* constants
	* @return bool
	*/
	public function setCalcMode(int $mode): bool
	{
	}

	/**
	* Creates a new conditional format
	*
	* @return ExcelConditionalFormat|false
	*/
	public function addConditionalFormat(): ExcelConditionalFormat|false
	{
	}

	/**
	* Creates a new format from a predefined cell style
	*
	* @param int $style One of ExcelBook::CELLSTYLE_* constants
	* @return ExcelFormat|false
	*/
	public function addFormatFromStyle(int $style): ExcelFormat|false
	{
	}

	/**
	* Removes VBA module from the workbook
	*
	* @return bool
	*/
	public function removeVBA(): bool
	{
	}

	/**
	* Removes printer settings from all sheets
	*
	* @return bool
	*/
	public function removePrinterSettings(): bool
	{
	}

	/**
	* Sets password for the workbook (xlsx only)
	*
	* @since libxl 5.0.0
	* @param string $password
	* @return bool
	*/
	public function setPassword(string $password): bool
	{
	}

	/**
	* Returns the DPI awareness mode
	*
	* @since libxl 5.0.0
	* @return int|false
	*/
	public function dpiAwareness(): int|false
	{
	}

	/**
	* Sets the DPI awareness mode
	*
	* @since libxl 5.0.0
	* @param int $value
	* @return bool
	*/
	public function setDpiAwareness(int $value): bool
	{
	}

	/**
	* Load Excel sheet info from raw data without loading the full file
	*
	* On success the book enters the same info-only mode as loadInfo().
	*
	* @see ExcelBook::loadInfo() for the methods available in info-only mode
	* @see ExcelBook::load() for success-only wrapper invalidation and failure diagnostics
	*
	* @since libxl 5.0.1
	* @param string $data
	* @return bool
	*/
	public function loadInfoRaw(string $data): bool
	{
	}

	/**
	* Returns the current workbook's error code
	*
	* LibXL load errors are emitted as warnings, not retained on this workbook.
	* @see ExcelBook::load()
	*
	* @since libxl 5.1.0
	* @return int|false
	*/
	public function errorCode(): int|false
	{
	}

	/**
	* Returns a conditional format by index
	*
	* @since libxl 5.1.0
	* @param int $index
	* @return ExcelConditionalFormat|false
	*/
	public function conditionalFormat(int $index): ExcelConditionalFormat|false
	{
	}

	/**
	* Returns the number of conditional formats
	*
	* @since libxl 5.1.0
	* @return int|false
	*/
	public function conditionalFormatSize(): int|false
	{
	}

	/**
	* Clears the workbook
	*
	* @since libxl 5.1.0
	* @return bool
	*/
	public function clear(): bool
	{
	}

	/**
	* Returns the core properties object for the workbook
	*
	* @return ExcelCoreProperties|false
	*/
	public function coreProperties(): ExcelCoreProperties|false
	{
	}

	/**
	* Removes all phonetic runs from the workbook
	*
	* @return bool
	*/
	public function removeAllPhonetics(): bool
	{
	}

} // end ExcelBook