---
name: "PPI::Cache"
section: "3pm"
platform: "linux"
package: "perl-ppi"
version: "1.291-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/PPI::Cache"
---

# PPI::Cache(3pm)

The PPI Document Caching Layer

## NAME

PPI::Cache - The PPI Document Caching Layer

## SYNOPSIS

```
  # Set the cache
  use PPI::Cache path => '/var/cache/ppi-cache';

  # Manually create a cache
  my $Cache = PPI::Cache->new(
      path     => '/var/cache/perl/class-PPI',
      readonly => 1,
  );
```

## DESCRIPTION

`"PPI::Cache"` provides the default caching functionality for PPI.

It integrates automatically with PPI itself. Once enabled, any attempt to load a document from the filesystem will be cached via cache.

Please note that creating a PPI::Document from raw source or something other object will **not** be cached.

### Using PPI::Cache

The most common way of using `"PPI::Cache"` is to provide parameters to the `"use"` statement at the beginning of your program.

```
  # Load the class but do not set a cache
  use PPI::Cache;

  # Use a fairly normal cache location
  use PPI::Cache path => '/var/cache/ppi-cache';
```

Any of the arguments that can be provided to the `"new"` constructor can also be provided to `"use"`.

## METHODS

### new param =\> $value, ...

The `"new"` constructor creates a new standalone cache object.

It takes a number of parameters to control the cache.

- path

  The `"path"` param sets the base directory for the cache. It must already exist, and must be writable.

- readonly

  The `"readonly"` param is a true/false flag that allows the use of an existing cache by a less-privileged user (such as the web user).

  Existing documents will be retrieved from the cache, but new documents will not be written to it.

Returns a new `"PPI::Cache"` object, or dies on error.

### path

The `"path"` accessor returns the path on the local filesystem that is the root of the cache.

### readonly

The `"readonly"` accessor returns true if documents should not be written to the cache.

### get\_document $md5sum \| \\$source

The `"get_document"` method checks to see if a Document is stored in the cache and retrieves it if so.

### store\_document $Document

The `"store_document"` method takes a PPI::Document as argument and explicitly adds it to the cache.

Returns true if saved, or `"undef"` (or dies) on error.

FIXME (make this return either one or the other, not both)

## TO DO

\- Finish the basic functionality

\- Add support for use PPI::Cache auto-setting `$PPI::Document::CACHE`

## SUPPORT

See the support section in the main module.

## AUTHOR

Adam Kennedy \<adamk@cpan.org\>

## COPYRIGHT

Copyright 2005 - 2011 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.