1<?php
2/**
3 * Base class for consent storage handlers.
4 *
5 * @package SimpleSAMLphp
6 * @author Olav Morken <olav.morken@uninett.no>
7 * @author JAcob Christiansen <jach@wayf.dk>
8 */
9abstract class sspmod_consent_Store
10{
11    /**
12     * Constructor for the base class.
13     *
14     * This constructor should always be called first in any class which implements this class.
15     *
16     * @param array &$config The configuration for this storage handler.
17     */
18    protected function __construct(&$config)
19    {
20        assert(is_array($config));
21    }
22
23
24    /**
25     * Check for consent.
26     *
27     * This function checks whether a given user has authorized the release of the attributes identified by
28     * $attributeSet from $source to $destination.
29     *
30     * @param string $userId        The hash identifying the user at an IdP.
31     * @param string $destinationId A string which identifyes the destination.
32     * @param string $attributeSet  A hash which identifies the attributes.
33     *
34     * @return bool True if the user has given consent earlier, false if not
35     *              (or on error).
36     */
37    abstract public function hasConsent($userId, $destinationId, $attributeSet);
38
39
40    /**
41     * Save consent.
42     *
43     * Called when the user asks for the consent to be saved. If consent information for the given user and destination
44     * already exists, it should be overwritten.
45     *
46     * @param string $userId        The hash identifying the user at an IdP.
47     * @param string $destinationId A string which identifyes the destination.
48     * @param string $attributeSet  A hash which identifies the attributes.
49     *
50     * @return bool True if consent is succesfully saved otherwise false.
51     */
52    abstract public function saveConsent($userId, $destinationId, $attributeSet);
53
54
55    /**
56     * Delete consent.
57     *
58     * Called when a user revokes consent for a given destination.
59     *
60     * @param string $userId        The hash identifying the user at an IdP.
61     * @param string $destinationId A string which identifyes the destination.
62     *
63     * @return mixed Should be the number of consent deleted.
64     */
65    abstract public function deleteConsent($userId, $destinationId);
66
67
68    /**
69     * Delete all consents.
70     *
71     * Called when a user revokes all consents
72     *
73     * @param string $userId The hash identifying the user at an IdP.
74     *
75     * @return mixed Should be the number of consent removed
76     *
77     * @throws Exception
78     */
79    public function deleteAllConsents($userId)
80    {
81        throw new Exception('Not implemented: deleteAllConsents()');
82    }
83
84
85    /**
86     * Get statistics for all consent given in the consent store
87     *
88     * @return mixed Statistics from the consent store
89     *
90     * @throws Exception
91     */
92    public function getStatistics()
93    {
94        throw new Exception('Not implemented: getStatistics()');
95    }
96
97
98    /**
99     * Retrieve consents.
100     *
101     * This function should return a list of consents the user has saved.
102     *
103     * @param string $userId The hash identifying the user at an IdP.
104     *
105     * @return array Array of all destination ids the user has given consent for.
106     */
107    abstract public function getConsents($userId);
108
109
110    /**
111     * Parse consent storage configuration.
112     *
113     * This function parses the configuration for a consent storage method. An exception will be thrown if
114     * configuration parsing fails.
115     *
116     * @param mixed $config The configuration.
117     *
118     * @return sspmod_consent_Store An object which implements the sspmod_consent_Store class.
119     *
120     * @throws Exception if the configuration is invalid.
121     */
122    public static function parseStoreConfig($config)
123    {
124        if (is_string($config)) {
125            $config = array($config);
126        }
127
128        if (!is_array($config)) {
129            throw new Exception('Invalid configuration for consent store option: '.var_export($config, true));
130        }
131
132        if (!array_key_exists(0, $config)) {
133            throw new Exception('Consent store without name given.');
134        }
135
136        $className = SimpleSAML\Module::resolveClass(
137            $config[0],
138            'Consent_Store',
139            'sspmod_consent_Store'
140        );
141
142        unset($config[0]);
143        return new $className($config);
144    }
145}
146