File Coverage

blib/lib/Nile/Setting.pm
Criterion Covered Total %
statement 3 55 5.4
branch 0 16 0.0
condition 0 9 0.0
subroutine 1 14 7.1
pod 0 11 0.0
total 4 105 3.8


line stmt bran cond sub pod time code
1             # Copyright Infomation
2             #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3             # Author : Dr. Ahmed Amin Elsheshtawy, Ph.D.
4             # Website: https://github.com/mewsoft/Nile, http://www.mewsoft.com
5             # Email : mewsoft@cpan.org, support@mewsoft.com
6             # Copyrights (c) 2014-2015 Mewsoft Corp. All rights reserved.
7             #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
8             package Nile::Setting;
9              
10             our $VERSION = '0.54';
11             our $AUTHORITY = 'cpan:MEWSOFT';
12              
13             =pod
14              
15             =encoding utf8
16              
17             =head1 NAME
18              
19             Nile::Setting - Application global settings database table manager.
20              
21             =head1 SYNOPSIS
22            
23             # get setting object instance
24             $setting = $self->app->setting;
25              
26             # load settings from database to the setting object.
27             $setting->load("settings", "name", "value");
28              
29             # get settings
30             say $setting->get("email");
31             say $setting->get("website", "default value");
32            
33             # automatic getter support
34             say $setting->email; # same as $setting->get('email');
35              
36             # set settings variables.
37             $setting->set("page_views", $count);
38             $setting->set(%vars);
39              
40             # automatic setter support
41             $setting->email('ahmed@mewsoft.com'); # same as $setting->set('email', 'ahmed@mewsoft.com');
42              
43             # delete settings from memory and database table.
44             $setting->delete(@names);
45              
46             =head1 DESCRIPTION
47              
48             Nile::Setting - Application global settings database table manager.
49              
50             This class to manage an optional application shared settings database table the same way you share the var and config object.
51              
52             Example of a suggested database table structure.
53              
54             CREATE TABLE settings (
55             name varchar(255), # name_column
56             value varchar(255) # value_column, change type to TEXT if needed
57             ) ENGINE=InnoDB default CHARACTER SET=utf8;
58              
59             Then you need to call the load setting once at the start of the application after you connect to the
60             database.
61            
62             # get setting object instance
63             $setting = $self->app->setting;
64              
65             # load settings from database to the setting object.
66             $setting->load("settings", "name", "value");
67              
68             Now you can get, set and delete the settings anywhere in your application.
69              
70             # get settings
71             say $setting->get("email");
72             say $setting->get("website", "default value");
73            
74             # automatic getter support
75             say $setting->email; # same as $setting->get('email');
76              
77             # set settings variables.
78             $setting->set("page_views", $count);
79             $setting->set(%vars);
80              
81             # automatic setter support
82             $setting->email('ahmed@mewsoft.com'); # same as $setting->set('email', 'ahmed@mewsoft.com');
83              
84             # delete settings from memory and database table.
85             $setting->delete(@names);
86              
87             =cut
88              
89 1     1   5 use Nile::Base;
  1         1  
  1         8  
90              
91             #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
92             =head2 setting_table_name()
93            
94             # set database settings table name
95             $setting->setting_table_name("settings");
96              
97             # get database settings table name
98             $setting->setting_table_name;
99              
100             Get and set the settings database table name.
101              
102             =cut
103              
104             has 'setting_table_name' => (
105             is => 'rw',
106             default => 'settings',
107             );
108              
109             =head2 setting_name_column()
110            
111             # set settings table column name for the 'name_column'.
112             $setting->setting_name_column("name");
113              
114             # get settings table column name for the 'name_column'.
115             $setting->setting_name_column;
116              
117             Get and set the settings database table column name.
118              
119             =cut
120              
121             has 'setting_name_column' => (
122             is => 'rw',
123             default => 'name',
124             );
125              
126             =head2 setting_value_column()
127            
128             # set settings table column name for the 'value_column'.
129             $setting->setting_value_column("value");
130              
131             # get settings table column name for the 'value_column'.
132             $setting->setting_value_column;
133              
134             Get and set the settings database table column value_column.
135              
136             =cut
137              
138             has 'setting_value_column' => (
139             is => 'rw',
140             default => 'value',
141             );
142             #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
143             sub AUTOLOAD {
144 0     0     my ($self) = shift;
145              
146 0           my ($class, $method) = our $AUTOLOAD =~ /^(.*)::(\w+)$/;
147              
148 0 0         if ($self->can($method)) {
149 0           return $self->$method(@_);
150             }
151              
152 0 0         if (@_) {
153 0           $self->{vars}->{$method} = $_[0];
154             }
155             else {
156 0           return $self->{vars}->{$method};
157             }
158             }
159             #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
160             sub main {
161 0     0 0   my ($self, $arg) = @_;
162 0           my $app = $self->app;
163 0           $self->load;
164             }
165             #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
166             =head2 load()
167            
168             # load settings from database to the setting object.
169             $setting->load($db_table, $name_column, $value_column);
170              
171             Load the settings from database table to the setting object. This method can be chained.
172              
173             =cut
174              
175             sub load {
176 0     0 0   my ($self, $table, $name, $value) = @_;
177            
178 0   0       $table ||= $self->app->config->get("settings/table");
179 0   0       $name ||= $self->app->config->get("settings/name");
180 0   0       $value ||= $self->app->config->get("settings/value");
181              
182 0 0         $self->table($table) if ($table);
183 0 0         $self->name($name) if ($name);
184 0 0         $self->value($value) if ($value);
185              
186 0           $self->{vars} = $self->app->db->colhash("select ".$self->name.", ".$self->value." from ".$self->table);
187 0           $self;
188             }
189             #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
190             =head2 unload()
191            
192             # clears all settings from memory.
193             $setting->unload;
194              
195             Resets the setting object and clear all settings from memory. This does not update the database table.
196             This method can be chained.
197              
198             =cut
199              
200             sub unload {
201 0     0 0   my ($self) = @_;
202 0           $self->{vars} = +{};
203 0           $self;
204             }
205             #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
206             =head2 vars()
207            
208             # get all settings as a hash or a hash ref.
209             %vars = $setting->vars();
210             $vars = $setting->vars();
211              
212             Returns all settings as a hash or a hash reference.
213              
214             =cut
215              
216             sub vars {
217 0     0 0   my ($self) = @_;
218 0           return $self->{vars};
219             }
220             #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
221             =head2 set()
222            
223             # set settings variables.
224             $setting->set("page_views", $count);
225             $setting->set(%vars);
226              
227             # automatic setter support
228             $setting->email('ahmed@mewsoft.com'); # same as $setting->set('email', 'ahmed@mewsoft.com');
229              
230             Set settings variables.
231              
232             =cut
233              
234             sub set {
235 0     0 0   my ($self, %vars) = @_;
236 0           my ($name, $value, $n, $v);
237            
238 0           while (($name, $value) = each %vars) {
239 0           $n = $self->app->db->quote($name);
240 0           $v = $self->app->db->quote($value);
241 0 0         if (exists $self->{vars}->{$name}) {
242 0           $self->app->db->run(qq{update $self->table set $self->name=$n, $self->value=$v});
243             }
244             else {
245 0           $self->app->db->run(qq{insert into $self->table set $self->name=$n, $self->value=$v});
246             }
247 0           $self->{vars}->{$name} = $value;
248             }
249              
250 0           $self;
251             }
252             #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
253             =head2 get()
254            
255             # get settings
256             say $setting->get("email");
257             say $setting->get("website", "default value");
258            
259             # automatic getter support
260             say $setting->email; # same as $setting->get('email');
261              
262             Returns settings variables.
263              
264             =cut
265              
266             sub get {
267 0     0 0   my ($self, $name, $default) = @_;
268 0 0         exists $self->{vars}->{$name}? $self->{vars}->{$name} : $default;
269             }
270             #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
271             =head2 list()
272            
273             # get a list of settings variables.
274             @vars = $setting->list(@names);
275              
276             Returns a list of settings variables.
277              
278             =cut
279              
280             sub list {
281 0     0 0   my ($self, @n) = @_;
282 0           @{$self->{vars}}{@n};
  0            
283             }
284             #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
285             =head2 keys()
286            
287             # returns all settings names.
288             @names = $setting->keys;
289              
290             Returns all settings names.
291              
292             =cut
293              
294             sub keys {
295 0     0 0   my ($self) = @_;
296 0           (keys %{$self->{vars}});
  0            
297             }
298             #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
299             =head2 exists()
300            
301             # check if a setting variable exist or not.
302             $found = $setting->exists($name);
303              
304             Check if a setting variable exist or not.
305              
306             =cut
307              
308             sub exists {
309 0     0 0   my ($self, $name) = @_;
310 0           exists $self->{vars}->{$name};
311             }
312             #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
313             =head2 delete()
314            
315             # delete settings from memory and database table.
316             $setting->delete(@names);
317              
318             Delete a list of settings from memory and database table..
319              
320             =cut
321              
322             sub delete {
323 0     0 0   my ($self, @n) = @_;
324 0           $self->app->db->run(qq{delete from $self->table where $self->name=} . $self->app->db->quote($_)) for @n;
325 0           delete $self->{vars}->{$_} for @n;
326             }
327             #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
328             =head2 clear()
329            
330             # delete all settings from memory and database table.
331             $setting->clear(1);
332              
333             Delete all settings from memory and database table. This can not be undone. You must pass a true value for the
334             function as a confirmation that you want to do the job.
335              
336             =cut
337              
338             sub clear {
339 0     0 0   my ($self, $confirm) = @_;
340 0 0         return unless ($confirm);
341 0           $self->app->db->run(q{delete from $self->table});
342 0           $self->{vars} = +{};
343             }
344             #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
345 0     0     sub DESTROY {
346             }
347             #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
348              
349             =pod
350              
351             =head1 Bugs
352              
353             This project is available on github at L<https://github.com/mewsoft/Nile>.
354              
355             =head1 HOMEPAGE
356              
357             Please visit the project's homepage at L<https://metacpan.org/release/Nile>.
358              
359             =head1 SOURCE
360              
361             Source repository is at L<https://github.com/mewsoft/Nile>.
362              
363             =head1 SEE ALSO
364              
365             See L<Nile> for details about the complete framework.
366              
367             =head1 AUTHOR
368              
369             Ahmed Amin Elsheshtawy, احمد امين الششتاوى <mewsoft@cpan.org>
370             Website: http://www.mewsoft.com
371              
372             =head1 COPYRIGHT AND LICENSE
373              
374             Copyright (C) 2014-2015 by Dr. Ahmed Amin Elsheshtawy احمد امين الششتاوى mewsoft@cpan.org, support@mewsoft.com,
375             L<https://github.com/mewsoft/Nile>, L<http://www.mewsoft.com>
376              
377             This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
378              
379             =cut
380              
381             1;