Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Put link of documentation on README.md and Close #185 #191

Merged
merged 8 commits into from
Oct 25, 2014
Merged

Put link of documentation on README.md and Close #185 #191

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
66bf0f6
Put link of documentation on README.md
Oct 24, 2014
2c0d4ac
Put an example on README
Oct 25, 2014
ddd311b
Fix typo and remove unecessary explanation
Oct 25, 2014
f1168fb
Change example, use "virtual proxy" instead "Ghost object" :(
Oct 25, 2014
72c4f54
Fix typos and syntax wrongs
Oct 25, 2014
8dad702
Compact line of example
Oct 25, 2014
21d322f
Remove `Contributing` and `Credits` section
Oct 25, 2014
a5a8d9b
Remove return to the code example
Oct 25, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
150 changes: 8 additions & 142 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,11 @@ This library aims at providing abstraction for generating various kinds of [prox
[![Latest Stable Version](https://poser.pugx.org/ocramius/proxy-manager/v/stable.png)](https://packagist.org/packages/ocramius/proxy-manager)
[![Latest Unstable Version](https://poser.pugx.org/ocramius/proxy-manager/v/unstable.png)](https://packagist.org/packages/ocramius/proxy-manager)


## Documentation
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should probably keep an example on the readme :-)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can keep all examples on main readme so, and remove another md docs. Speak your mind @Ocramius

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@malukenho I'd remove the .md docs only once we've moved all the documentation to .rst (not yet planned)


You can learn about proxy pattern and how use **ProxyManager** on the [online documentation](http://ocramius.github.io/ProxyManager).
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

... and how TO use ProxyManager ...

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for spotting it!


## Installation

The suggested installation method is via [composer](https://getcomposer.org/):
Expand All @@ -24,11 +29,9 @@ The suggested installation method is via [composer](https://getcomposer.org/):
php composer.phar require ocramius/proxy-manager:1.0.*
```

## Lazy Loading Value Holders (Virtual Proxy)
## Proxy example

ProxyManager can generate [lazy loading value holders](http://www.martinfowler.com/eaaCatalog/lazyLoad.html),
which are virtual proxies capable of saving performance and memory for objects that require a lot of dependencies or
CPU cycles to be loaded: particularly useful when you may not always need the object, but are constructing it anyways.
Here's how you build a lazy loadable object with ProxyManager using a *Virtual Proxy*

```php
$factory = new \ProxyManager\Factory\LazyLoadingValueHolderFactory();
Expand All @@ -38,147 +41,10 @@ $proxy = $factory->createProxy(
function (& $wrappedObject, $proxy, $method, $parameters, & $initializer) {
$wrappedObject = new HeavyComplexObject(); // instantiation logic here
$initializer = null; // turning off further lazy initialization

return true;
}
);

$proxy->doFoo();
```

See the [complete documentation about lazy loading value holders](/docs/lazy-loading-value-holder.md)
in the `docs/` directory.

## Access Interceptor Value Holder

An access interceptor value holder is a smart reference that allows you to execute logic before
and after a particular method is executed or a particular property is accessed, and it allows to
manipulate parameters and return values depending on your needs.

```php
$factory = new \ProxyManager\Factory\AccessInterceptorValueHolderFactory();

$proxy = $factory->createProxy(
new \My\Db\Connection(),
array('query' => function () { echo "Query being executed!\n"; }),
array('query' => function () { echo "Query completed!\n"; })
);

$proxy->query(); // produces "Query being executed!\nQuery completed!\n"
```

See the [complete documentation about access interceptor value holders](/docs/access-interceptor-value-holder.md)
in the `docs/` directory.

## Access Interceptor Scope Localizer

An access interceptor scope localizer works exactly like an access interceptor value holder,
but it is safe to use to proxy fluent interfaces.

See the [complete documentation about access interceptor scope localizer](/docs/access-interceptor-scope-localizer.md)
in the `docs/` directory.

## Null Objects

A Null Object proxy implements the [null object pattern](http://en.wikipedia.org/wiki/Null_Object_pattern).

This kind of proxy allows you to have fallback logic in case loading of the wrapped value failed.

```php
$factory = new \ProxyManager\Factory\NullObjectFactory();

$proxy = $factory->createProxy('My\EntityObject');

$proxy->getName(); // empty return
```

A Null Object Proxy can be created from an object, a class name or an interface name:

```php
$factory = new \ProxyManager\Factory\NullObjectFactory();

$proxy = $factory->createProxy('My\EntityObjectInterface');
$proxy->getName(); // empty return

$proxy = $factory->createProxy($entity); // created from object
$proxy->getName(); // empty return
```

See the [complete documentation about null object proxy](/docs/null-object.md)
in the `docs/` directory.

## Ghost Objects


Similar to value holder, a ghost object is usually created to handle lazy loading.

The difference between a value holder and a ghost object is that the ghost object does not contain a real instance of
the required object, but handles lazy loading by initializing its own inherited properties.

ProxyManager can generate [lazy loading ghost objects](http://www.martinfowler.com/eaaCatalog/lazyLoad.html),
which are proxies used to save performance and memory for large datasets and graphs representing relational data.
Ghost objects are particularly useful when building data-mappers.

Additionally, the overhead introduced by ghost objects is very low when compared to the memory and performance overhead
caused by virtual proxies.

```php
$factory = new \ProxyManager\Factory\LazyLoadingGhostFactory();

$proxy = $factory->createProxy(
'MyApp\HeavyComplexObject',
function ($proxy, $method, $parameters, & $initializer) {
$initializer = null; // turning off further lazy initialization

// modify the proxy instance
$proxy->setFoo('foo');
$proxy->setBar('bar');

return true;
}
);

$proxy->doFoo();
```

See the [complete documentation about lazy loading ghost objects](/docs/lazy-loading-ghost-object.md)
in the `docs/` directory.

## Remote Object

A remote object proxy is an object that is located on a different system, but is used as if it was available locally.
There's various possible remote proxy implementations, which could be based on xmlrpc/jsonrpc/soap/dnode/etc.

This example uses the XML-RPC client of Zend Framework 2:

```php
interface FooServiceInterface
{
public function foo();
}

$factory = new \ProxyManager\Factory\RemoteObjectFactory(
new \ProxyManager\Factory\RemoteObject\Adapter\XmlRpc(
new \Zend\XmlRpc\Client('https://example.com/rpc-endpoint')
)
);

// proxy is your remote implementation
$proxy = $factory->createProxy('FooServiceInterface');

var_dump($proxy->foo());
```

See the [complete documentation about remote objects](https://github.com/Ocramius/ProxyManager/tree/master/docs/remote-object.md)
in the `docs/` directory.

## Contributing

Please read the [CONTRIBUTING.md](https://github.com/Ocramius/ProxyManager/blob/master/CONTRIBUTING.md) contents if you
wish to help out!

## Credits

The idea was originated by a [talk about Proxies in PHP OOP](http://marco-pivetta.com/proxy-pattern-in-php/) that I gave
at the [@phpugffm](https://twitter.com/phpugffm) in January 2013.

See the [online documentation](http://ocramius.github.io/ProxyManager) for more supported proxy types and examples.