Developer Documentation 번역 : 04.구성 설정

구성 설정

PHPExcel file을 스크립트에 인클루드하기에 앞서서 PHPExcel 객체를 인스턴스화 하거나 문서를 로드하기전에

설정할 수 있는 구성 옵션이 여러가지 있다.

1.Cell Caching

PHPExcel은 워크시트에서 cell당 평균 1kbyte를 차지하게 된다. 그래서 큰 문서일 경우 메모리를 빨리 소진하게 될 수 있다.

Cell Caching은 cell객체가 PHP 메모리보다 작은 사이즈를 유지하는 매커니즘을 디스크 혹은 APC, memcache혹은 Wincache에서 제공한다.

cell 데이터에 대해 엑세스하는 속도의 비용이 들긴 하지만 큰 문서에 대한 메모리 사용을 줄일 수 있다.

기본적으로 PHPExcel은 모든 Cell에 대해서 메모리를 유지하지만 이것에 대한 대안을 지정할 수 있다.

cell caching을 사용 하려면 반드시 PHPExcel_Setting::setCachiStorageMethod() 메서드를 호출해야 한다. 

이것은 당신이 사용하고자하는 캐싱 방식으로 전달한다.

$cacheMethod = PHPExcel_CachedObjectStorageFactory::cache_in_memory;

PHPExcel_Settings::setCacheStorageMethod($cacheMethod);

setCacheStorageMethod()가 성공하면 boolean의 true값을 실패하면 false값을 반환한다.

(예를 들어 APC가 활성화 되지 않았는데 APC에 캐시하려고 시도하는 경우)

각각의 워크시트에 대에 별도 의 캐시가 유지되며, 워크시트는 사용자가 설정한 캐싱 방법및 설정을 기반으로 인스턴스화 될때 자동으로 적용된다.

문서를 읽기 시작하거나 첫번째 워크 시트를 생성하기 시작한 때에는 구성 설정을 변경할 수 없다.

현재, 다음과 같은 캐싱 방법을 사용할 수 있습니다.

PHPExcel_CachedObjectStorageFactory::cache_in_memory

기본 값. 어떠한 캐싱 방법도 초기화 하지 않을 경우 PHPExcel이 사용하는 방법이다.

셀 개체는 현재의 PHP 메모리에 유지된다.

PHPExcel_CachedObjectStorageFactory::cache_in_memory_serialized

이 캐싱방법은 최소한의 오버헤드 성능과 메모리의 범위를 감소하여 직렬화된 객체의 배열로 PHP 메모리에 저장된다.

PHPExcel_CachedObjectStorageFactory::cache_in_memory_gzip

cache_in_memory_serialized는 직렬화된 오브젝트 배열로 셀의 메모리를 PHP에서 보유하고 메모리를 줄이기 위해 gzip으로 압축 하지만

셀을 읽거나 쓸때에 약간 느릴 수 있다.

PHPExcel_CachedObjectStorageFactory::cache_igbinary

메모리 셀의 객체를 직렬화 하는 PHPs igbinary 확장(사용 가능한 경우)을 사용한다.

일반적으로 빠르기도 하고 표준 PHP 직렬화보다 적은 메모리를 사용하지만, 대부분의 호스팅 환경에서 사용할 수 없다.

PHPExcel_CachedObjectStorageFactory::cache_to_discISAM

cache_to_discISAM를 사용하는 경우 모든 셀들은 임시 디스크파일에 보관된다,오로지 해당파일의 인덱스만 PHP메모리에 유지된다.

$cacheMethod = PHPExcel_CachedObjectStorageFactory:: cache_to_discISAM;

$cacheSettings = array( 

    'dir' => '/usr/local/tmp'

);

PHPExcel_Settings::setCacheStorageMethod($cacheMethod, $cacheSettings);

스크립트가 종료되면 임시 디스크 파일은 자동으로 삭제된다.

PHPExcel_CachedObjectStorageFactory::cache_to_phpTemp

cache_to_discISAM의 경우 cache_to_php를 사용하게 되면 모든 셀들이 php://temp에서 I/O stream 작동한다. 해당 파일의 인덱스만 PHP메모리에 유지된다.

$cacheMethod = PHPExcel_CachedObjectStorageFactory:: cache_to_phpTemp;

$cacheSettings = array( 

    'memoryCacheSize' => '8MB'

);

PHPExcel_Settings::setCacheStorageMethod($cacheMethod, $cacheSettings);

스크립트가 종료 될 때  php://temp 임시 파일은 자동으로 삭제됩니다.

PHPExcel_CachedObjectStorageFactory::cache_to_apc

cache_to_apc를 사용하는 경우, PHP메모리에 셀이 존재하는지 확인하여 APC와 인덱스에서 cell객체가 유지된다.

기본적으로 APC캐시는 600초의 시간제한을 가지며, 대부분의 응용 프로그램에서 충분히 사용된다.

초기화때 cache_to_APC를 변경할 수 있다.

$cacheMethod = PHPExcel_CachedObjectStorageFactory::cache_to_APC;

$cacheSettings = array( 

    'cacheTime' => 600

);

PHPExcel_Settings::setCacheStorageMethod($cacheMethod, $cacheSettings);

종료되면 스크립트는 모든 항목에 상관없이 CacheTime 값 즉 APC에서 삭제된다.

그래서 이 메커니즘을 사용하면 영구저장소에사용할 수 없다.

PHPExcel_CachedObjectStorageFactory::cache_to_memcache

cache_to_apc를 사용하는 경우, PHP메모리에 셀이 존재하는지 확인하여 APC와 인덱스에서 cell객체가 유지된다.

기본적으로 APC캐시는 600초의 시간제한을 가지며, 대부분의 응용 프로그램에서 충분히 사용된다.

초기화때 cache_to_APC를 변경할 수 있다.

$cacheMethod = PHPExcel_CachedObjectStorageFactory::cache_to_APC;

$cacheSettings = array( 

    'cacheTime' => 600

);

PHPExcel_Settings::setCacheStorageMethod($cacheMethod, $cacheSettings);

종료되면 스크립트는 모든 항목에 상관없이 CacheTime 값 즉 APC에서 삭제된다.

그래서 이 메커니즘을 사용하면 영구저장소에사용할 수 없다.

PHPExcel_CachedObjectStorageFactory::cache_to_memcache

cache_to_memcache를 사용하는 PHP메모리에 셀이 존재하는지 확인한 후  memcache와 index에 유지시킨다.

기본적으로 PHPExcel은 memcache가 localhost서버의 포트112211로 설정되어있다.

또한 memcache는 600초의 타임아웃을 가지고있고 만약 memcache가 다른 서나 포트에서 시행되는 경우엔

cache_to_memcahe의 기본값을 초기화하거나 변경할 수 없다.

$cacheMethod = PHPExcel_CachedObjectStorageFactory::cache_to_memcache;

$cacheSettings = array( 

    'memcacheServer' => 'localhost',

    'memcachePort'   => 11211,

    'cacheTime'      => 600

);

PHPExcel_Settings::setCacheStorageMethod($cacheMethod, $cacheSettings);

종료되면 스크립트는 모든 항목에 관계없이 cacheTime값, memcache가 삭제된다. 그래서 이 메커니즘을 사용하면 영구저장소에사용할 수 없다.

PHPExcel_CachedObjectStorageFactory::cache_to_wincache

cache_to_wincache를 사용하는 경우, PHP메모리에 셀이 존재하는지 확인하여 Wincache와 인덱스에서 cell객체가 유지된다.

기본적으로 APC캐시는 600초의 시간제한을 가지며, 대부분의 응용 프로그램에서 충분히 사용된다.

초기화때 cache_to_wincache를 변경할 수 있다.

$cacheMethod = PHPExcel_CachedObjectStorageFactory::cache_to_wincache;

$cacheSettings = array( 

    'cacheTime' => 600

);

PHPExcel_Settings::setCacheStorageMethod($cacheMethod, $cacheSettings);

종료되면 스크립트는 모든 항목에 관계없이 cacheTime값, Wincache에서 삭제된다. 그래서 이 메커니즘을 사용하면 영구저장소에사용할 수 없다.

PHPExcel_CachedObjectStorageFactory::cache_to_sqlite

SQLite2는 "in-memory" 셀 데이터 캐싱을 사용한다.

다른 캐싱 방법과는 달리 셀과 인덱스도 PHP의 메모리에 저장된다.

색인 데이터베이스 테이블을 휘애 PHP에 메모리에 모든 인덱스를 유지하고 

이렇게 하는것이 가장 효율적인 메모리 셀 캐싱 방법이다.

PHPExcel_CachedObjectStorageFactory::cache_to_sqlite3;

SQLite3는 "in-memory" 셀 데이터 캐싱을 사용한다.

다른 캐싱 방법과는 달리 셀과 인덱스도 PHP의 메모리에 저장된다.

색인 데이터베이스 테이블을 휘애 PHP에 메모리에 모든 인덱스를 유지하고 

이렇게 하는것이 가장 효율적인 메모리 셀 캐싱 방법이다.

Language/Locale

일부 현지화 요소는 PHPExcel에 포함되어있다. 설정을 변경하여 로케일을 설정할 수 있는데.

브라질 포르투갈어 로케일을 설정하려면

$locale = 'pt_br';

$validLocale = PHPExcel_Settings::setLocale($locale);

if (!$validLocale) {

    echo 'Unable to set locale to ' . $locale . " - reverting to en_us" . PHP_EOL;

}

포르투갈어 언어 파일을 사용할 수 없는 경우 다음의 setLocale() 메소드가 에러를 반환하고

포르투갈어(브라질)언어 파일을 사용할수 없게되면 미국영어(en_us)설정으로 사용된다. 

로케일이 현재 지원하는 언어와 지역 목록을 포함하여 사용할 수 있는 기능의 자세한 내용은

"Locale Settings for Formulae" 문서의 섹션에서 찾을 수 있다.

영어원문

Configuration Settings

Once you have included the PHPExcel files in your script, but before instantiating a PHPExcel object or loading a workbook file, there are a number of configuration options that can be set which will affect the subsequent behaviour of the script.

Cell Caching

PHPExcel uses an average of about 1k/cell in your worksheets, so large workbooks can quickly use up available memory. Cell caching provides a mechanism that allows PHPExcel to maintain the cell objects in a smaller size of memory, on disk, or in APC, memcache or Wincache, rather than in PHP memory. This allows you to reduce the memory usage for large workbooks, although at a cost of speed to access cell data.

By default, PHPExcel still holds all cell objects in memory, but you can specify alternatives. To enable cell caching, you must call the PHPExcel_Settings::setCacheStorageMethod() method, passing in the caching method that you wish to use.

$cacheMethod = PHPExcel_CachedObjectStorageFactory::cache_in_memory;

PHPExcel_Settings::setCacheStorageMethod($cacheMethod);

setCacheStorageMethod() will return a boolean true on success, false on failure (for example if trying to cache to APC when APC is not enabled).

A separate cache is maintained for each individual worksheet, and is automatically created when the worksheet is instantiated based on the caching method and settings that you have configured. You cannot change the configuration settings once you have started to read a workbook, or have created your first worksheet.

Currently, the following caching methods are available.

PHPExcel_CachedObjectStorageFactory::cache_in_memory

The default. If you don't initialise any caching method, then this is the method that PHPExcel will use. Cell objects are maintained in PHP memory as at present.

PHPExcel_CachedObjectStorageFactory::cache_in_memory_serialized

Using this caching method, cells are held in PHP memory as an array of serialized objects, which reduces the memory footprint with minimal performance overhead.

PHPExcel_CachedObjectStorageFactory::cache_in_memory_gzip

Like cache_in_memory_serialized, this method holds cells in PHP memory as an array of serialized objects, but gzipped to reduce the memory usage still further, although access to read or write a cell is slightly slower.

PHPExcel_CachedObjectStorageFactory::cache_igbinary

Uses PHPs igbinary extension (if its available) to serialize cell objects in memory. This is normally faster and uses less memory than standard PHP serialization, but isnt available in most hosting environments.

PHPExcel_CachedObjectStorageFactory::cache_to_discISAM

When using cache_to_discISAM all cells are held in a temporary disk file, with only an index to their location in that file maintained in PHP memory. This is slower than any of the cache_in_memory methods, but significantly reduces the memory footprint. By default, PHPExcel will use PHP's temp directory for the cache file, but you can specify a different directory when initialising cache_to_discISAM.

$cacheMethod = PHPExcel_CachedObjectStorageFactory:: cache_to_discISAM;
$cacheSettings = array( 
    'dir' => '/usr/local/tmp'
);
PHPExcel_Settings::setCacheStorageMethod($cacheMethod, $cacheSettings);

The temporary disk file is automatically deleted when your script terminates.

PHPExcel_CachedObjectStorageFactory::cache_to_phpTemp

Like cache_to_discISAM, when using cache_to_phpTemp all cells are held in the php://temp I/O stream, with only an index to their location maintained in PHP memory. In PHP, the php://memory wrapper stores data in the memory: php://temp behaves similarly, but uses a temporary file for storing the data when a certain memory limit is reached. The default is 1 MB, but you can change this when initialising cache_to_phpTemp.

$cacheMethod = PHPExcel_CachedObjectStorageFactory:: cache_to_phpTemp;
$cacheSettings = array( 
    'memoryCacheSize' => '8MB'
);
PHPExcel_Settings::setCacheStorageMethod($cacheMethod, $cacheSettings);

The php://temp file is automatically deleted when your script terminates.

PHPExcel_CachedObjectStorageFactory::cache_to_apc

When using cache_to_apc, cell objects are maintained in APC with only an index maintained in PHP memory to identify that the cell exists. By default, an APC cache timeout of 600 seconds is used, which should be enough for most applications: although it is possible to change this when initialising cache_to_APC.

$cacheMethod = PHPExcel_CachedObjectStorageFactory::cache_to_APC;
$cacheSettings = array( 
    'cacheTime' => 600
);
PHPExcel_Settings::setCacheStorageMethod($cacheMethod, $cacheSettings);

When your script terminates all entries will be cleared from APC, regardless of the cacheTime value, so it cannot be used for persistent storage using this mechanism.

PHPExcel_CachedObjectStorageFactory::cache_to_memcache

When using cache_to_memcache, cell objects are maintained in memcache with only an index maintained in PHP memory to identify that the cell exists.

By default, PHPExcel looks for a memcache server on localhost at port 11211. It also sets a memcache timeout limit of 600 seconds. If you are running memcache on a different server or port, then you can change these defaults when you initialise cache_to_memcache:

$cacheMethod = PHPExcel_CachedObjectStorageFactory::cache_to_memcache;
$cacheSettings = array( 
    'memcacheServer' => 'localhost',
    'memcachePort'   => 11211,
    'cacheTime'      => 600
);
PHPExcel_Settings::setCacheStorageMethod($cacheMethod, $cacheSettings);

When your script terminates all entries will be cleared from memcache, regardless of the cacheTime value, so it cannot be used for persistent storage using this mechanism.

PHPExcel_CachedObjectStorageFactory::cache_to_wincache

When using cache_to_wincache, cell objects are maintained in Wincache with only an index maintained in PHP memory to identify that the cell exists. By default, a Wincache cache timeout of 600 seconds is used, which should be enough for most applications: although it is possible to change this when initialising cache_to_wincache.

$cacheMethod = PHPExcel_CachedObjectStorageFactory::cache_to_wincache;
$cacheSettings = array( 
    'cacheTime' => 600
);
PHPExcel_Settings::setCacheStorageMethod($cacheMethod, $cacheSettings);

When your script terminates all entries will be cleared from Wincache, regardless of the cacheTime value, so it cannot be used for persistent storage using this mechanism.

PHPExcel_CachedObjectStorageFactory::cache_to_sqlite

Uses an SQLite 2 "in-memory" database for caching cell data. Unlike other caching methods, neither cells nor an index are held in PHP memory - an indexed database table makes it unnecessary to hold any index in PHP memory, which makes this the most memory-efficient of the cell caching methods.

PHPExcel_CachedObjectStorageFactory::cache_to_sqlite3;

Uses an SQLite 3 "in-memory" database for caching cell data. Unlike other caching methods, neither cells nor an index are held in PHP memory - an indexed database table makes it unnecessary to hold any index in PHP memory, which makes this the most memory-efficient of the cell caching methods.

Language/Locale

Some localisation elements have been included in PHPExcel. You can set a locale by changing the settings. To set the locale to Brazilian Portuguese you would use:

$locale = 'pt_br';
$validLocale = PHPExcel_Settings::setLocale($locale);
if (!$validLocale) {
    echo 'Unable to set locale to ' . $locale . " - reverting to en_us" . PHP_EOL;
}

If Brazilian Portuguese language files aren't available, then Portuguese will be enabled instead: if Portuguese language files aren't available, then the setLocale() method will return an error, and American English (en_us) settings will be used throughout.

More details of the features available once a locale has been set, including a list of the languages and locales currently supported, can be found in the section of this document entitled "Locale Settings for Formulae".